klypix-mcp

# Every project gets a brain.

Shared project memory for **Claude Code, Codex, Cursor** and other MCP coding tools. One
`brain.klypix` file, committed with your code, carries the project's decisions, corrections and open
questions across sessions and between tools. Corrections supersede stale decisions; sessions declare
the files they expect to touch and get warned about same-machine overlap. Versioned in Git. Served
over MCP by a process on your machine; Klypix uploads nothing (your agent's provider still receives
what the agent reads). Integration depth differs by host — see
[Supported hosts](#supported-hosts-and-their-integration-level).

![Two real MCP sessions on one project: Session B declares a file Session A already declared, and the server's exact-file-overlap warning fires; Session A then records a correction that supersedes its stale card](docs/demo/demo.gif)

<sub>Real output, not a mockup: both panes run a real MCP client against this server
([docs/demo/](docs/demo/) — the GIF is rendered by CI from a scripted tape against this server, not
hand-recorded, and re-rendered when the server's responses change).</sub>

Run this inside your project:

```bash
npx klypix-mcp install
```

It creates `brain.klypix` if the project has none, wires the editors it finds on this machine,
registers the `.klypix` merge driver if this is a git repo, and exits only after a real MCP
handshake has counted the tools that answered.

[![Claude Code](https://img.shields.io/badge/Claude_Code-5_lifecycle_hooks-475569?style=flat-square)](#supported-hosts-and-their-integration-level)
[![Codex](https://img.shields.io/badge/Codex-native_MCP_%2B_presence-475569?style=flat-square)](#supported-hosts-and-their-integration-level)
[![Cursor](https://img.shields.io/badge/Cursor-MCP_config_%2B_rules-475569?style=flat-square)](#supported-hosts-and-their-integration-level)
[![Gemini CLI](https://img.shields.io/badge/Gemini_CLI-MCP_config_%2B_rules-475569?style=flat-square)](#supported-hosts-and-their-integration-level)

<sub>Host badges name the **integration level**, not a flat "compatible" — the levels and what is
actually tested are in [Supported hosts](#supported-hosts-and-their-integration-level).</sub>

> **One project. Many agents. One current understanding.**

Klypix does not launch, run, supervise, or replace your agents. It is not an agent runtime, a model
router, a worktree manager, or a replacement for Git. It holds what the project currently believes.

[![CI](https://img.shields.io/github/actions/workflow/status/dahshanlabs/klypix-mcp/ci.yml?branch=master&style=flat-square&label=CI)](https://github.com/dahshanlabs/klypix-mcp/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/klypix-mcp?style=flat-square)](https://www.npmjs.com/package/klypix-mcp)
[![License](https://img.shields.io/github/license/dahshanlabs/klypix-mcp?style=flat-square)](LICENSE)
[![Node](https://img.shields.io/node/v/klypix-mcp?style=flat-square)](package.json)
[![MCP](https://img.shields.io/badge/MCP-server-475569?style=flat-square)](https://modelcontextprotocol.io)
[![Glama score](https://glama.ai/mcp/servers/dahshanlabs/klypix-mcp/badges/score.svg)](https://glama.ai/mcp/servers/dahshanlabs/klypix-mcp)
[![bench](https://img.shields.io/badge/npx_klypix--mcp_bench-10_writers_%C2%B7_0_lost-475569?style=flat-square)](BENCHMARKS.md)

## See the shared project brain in action

[![Watch the 2 minute 21 second KLYPIX Brain product walkthrough](https://raw.githubusercontent.com/dahshanlabs/klypix-mcp/master/docs/assets/klypix-brain-showcase-readme.jpg)](https://klypix.com/developers#demo)

Watch how current decisions, corrections, evidence, and active work stay visible to people and
carry forward into supported coding-agent sessions.

**[Watch the 2:21 showcase with sound](https://klypix.com/developers#demo)**

---

## The problem

You are running more than one coding agent on one codebase — a Claude Code session here, Codex in
another terminal, Cursor open on the side. Each one has excellent memory of *itself* and none of
the others:

- Every new session starts from zero, and you explain the same architecture again.
- Codex does not know what Claude learned an hour ago.
- One agent implements an approach the team already rejected, because the reason it was rejected
  lived in a chat that ended.
- Two sessions start changing the same files and nobody finds out until review.
- Git stores the code history. It does not store a reliable history of project *intent*.

Your agents may run independently. Their project understanding should not.

---

## 60 seconds: two agents, one project

Session A — Claude Code, in your repo:

```jsonc
brain_sync { intent: "rewrite the auth token refresh", files: ["src/auth/token.ts"] }
// → task-relevant memory capsule (bounded, ~2.8KB)
// → peers: none
```

Session B — Codex, same repo, half a minute later:

```jsonc
brain_sync { intent: "add rate limiting to the auth routes",
             files: ["src/auth/token.ts", "src/auth/routes.ts"] }
// → task capsule
// → peers: 1 active session (claude-code) — "rewrite the auth token refresh"
// → overlap: src/auth/token.ts — declared by both sessions
```

Session A gets the same overlap surfaced on its next KLYPIX action. Neither edit is blocked — the
warning is advisory, and both sides only see the overlap because both declared the files they
expected to touch.

Then the brain pushes back before the decision, not after:

```jsonc
brain_challenge { "move token storage to localStorage" }
// → "reversed on June 12 — here's the correction card, captured by a different agent."
```

And the decision is kept where the next session will find it:

```jsonc
brain_note { text: "Token refresh moves to an httpOnly cookie; localStorage was reversed 2026-06-12." }
```

Prove all of this on your own machine, against the exact build you installed, with two real
isolated MCP clients:

```bash
npx klypix-mcp conformance
```

It runs in a temporary fixture and touches nothing else. It checks tool discovery, task memory,
truthful peer reporting, overlap surfacing, proactive logging, and in-band delivery of a peer note.
It verifies 15 required coordination behaviours — not every tool, and not the retrieval engine.

---

## Quick start

**You need Node.js 20 or newer** (`node -v` to check). Every way of connecting runs the server with
`node` — `npx`, the installed bundle, and the entry KLYPIX's Settings buttons write — and none of them
checks for Node first.

Run this **inside your project**:

```bash
npx klypix-mcp install
```

One command for supported editors detected on this machine. It finds the project root (walking up,
so running it from `src/` is fine), gives the project a brain if it doesn't have one, wires the
agent tools you actually have installed, registers the card-level `.klypix` merge driver if it's a
git repo, and then **proves the result** before it exits:

```text
  project   E:\work\api  (git repository root)
  brain     created brain.klypix — a starter brain, ready for its first decision
  editors   Claude Code · Cursor · Codex · Gemini CLI · Antigravity · VS Code
  wired     9 file(s) · 9 updated   (skipped 5 for tools you don't have)
  git       .klypix merge driver registered
  verified  ✓ 25 tools reachable via .mcp.json (892ms)
```

That last line is the point. MCP config fails **silently** — a wrong entry means the server never
starts, the agent quietly loses every brain verb, and nothing reports an error. So `install` opens
a real stdio handshake against the config it just wrote and counts the tools that answered. A
broken entry dies in ~100ms with `Connection closed` and is reported, not shipped.

What goes where:

- **Machine-global, once** — the engine + runtime in `~/.claude/project-brain`, Claude Code's five
  lifecycle hooks in `~/.claude/settings.json`, and the `~/.codex/AGENTS.md` guidance block. Claude
  Code is therefore covered in every project on that machine that has a `./brain.klypix`.
- **Per project** — MCP config and rules for Cursor, Codex, Cline, Windsurf, Copilot, Gemini CLI /
  Antigravity and Aider. Run `install` once inside each project.

Three things it deliberately will **not** do:

- **Write for editors you don't have.** Config is projected only for hosts detected on this
  machine — a two-person team using one editor no longer commits rules for six they never opened.
  A file your project *already* carries stays maintained regardless, so you can't silently stop
  updating your team's committed configs.
- **Wire a directory that isn't a project.** It refuses your home folder, a drive root, and
  anything with no brain, no git repo and no project manifest. A mistyped command can't seed a
  brain into `C:\Users\you`.
- **Replace a project-owned server.** A repo-relative launch like
  `node scripts/klypix-mcp-server.mjs` is deliberate — it resolves offline and rides a bundle the
  repo version-gates — so it's left byte-identical and reported. An explicit `link` still rewrites
  everything: an action you didn't ask for stays more conservative than one you did.

Opt out with `--no-project` (CI images, scripted provisioning). `--json` emits the report as
structured data; `--verify-all` handshakes every written config instead of one.

Optional, opt-in, and approved inside Codex itself:

```bash
npx klypix-mcp install --codex-hooks
```

Six Codex lifecycle hooks that add automatic per-prompt context injection and a pre-edit
file-overlap warning. Codex owns the trust decision and will ask you to review them.
`brain_doctor` reports this layer separately as off, execution-unverified, or active. Even with it
on, **Codex never captures decisions automatically** — the Codex hook never writes the brain.

**Re-project everything explicitly:**

```bash
npx klypix-mcp link
```

`install` already does this for the editors you have. Reach for `link` when you want all 14
managed, hash-stamped files regardless of what's installed — MCP server config for six hosts plus
r