klypix-mcp

# Every project gets a brain.

**Active state management for multi-agent coding — a local-first active context engine with a shared brain.**
*One project. One shared understanding.*

[![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)
[![bench](https://img.shields.io/badge/npx_klypix--mcp_bench-10_writers_%C2%B7_0_lost-475569?style=flat-square)](BENCHMARKS.md)

[![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 actively managed project brain for multi-agent coding.** `klypix-mcp` keeps one versioned
`brain.klypix` in your repo: the project's active state — current decisions, corrections, evidence
anchors, open questions, active work, and handoffs. Corrections supersede stale decisions,
`brain_challenge` tests proposed decisions against standing rules and reversed approaches, and
sessions declare their scope and get warned about same-machine file overlap. Agents read it and
write to it over MCP. You read it and correct it in the [KLYPIX app](https://klypix.com).

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

![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 re-rendered by CI from a scripted tape, so it can never
drift from what the product actually does).</sub>

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 is the layer underneath them that holds
what the project currently believes.

## 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 the 22 tools, and not the retrieval engine.

---

## Quick start

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 lossless `.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       lossless .klypix merge driver registered
  verified  ✓ 22 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
rules files for eight — or to repair drift. Managed blocks are merged into your existing
instruction files and never clobber your content.

```bash
npx klypix-mcp link --check    # audits without writing; exits non-zero on drift
```

> Either form works, and both are safe in CI: `npx -p klypix-mcp klypix-link --check` used to
> drop `--check` and write anyway — fixed, and locked by `test/cli-args.mjs`, which asserts the
> standalone bin and the dispatcher parse arguments identically.

**Give a project a brain** by dropping a `brain.klypix` into it —