klypix-mcp

The shared project brain for your coding agents.

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, holds the project's decisions, corrections and open questions. Supported agents read it at the start of a task and add to it as they work; how much of that happens on its own depends on the host. People can open the same file and correct it.

A 14-second cut of the sessions film from klypix.com. Real terminal output is further down.

▶ Watch: For coding teams (40 s, with sound) · Correct it once (20 s) · Full tour (4 min) · KLYPIX network

Install in three steps

You need Node.js 20 or newer (node -v).

1. Run this inside your project:

   npx klypix-mcp install

   It gives the project a brain.klypix if it has none, wires the editors it finds on this machine, and checks that the tools answer before it exits.

2. Reopen your coding tool, or reconnect its MCP server, and allow the KLYPIX tools if it asks.

3. Check it. Run npx klypix-mcp doctor, then record your first decision and correction and ask for it from a fresh session.

What you get

• Decisions that carry over. The next session, in the same tool or another one, starts from what the project already decided: on its own in Claude Code, and when the agent calls brain_sync in other hosts. A correction replaces the old decision, and the old card stays as history.
• A heads-up when work overlaps. Each session says what it is doing and which files it expects to touch. When two sessions name the same file, both are warned. For overlapping work KLYPIX warns; it never blocks an edit. This works on one computer. With KLYPIX network installed on both computers (klypix-mcp 1.106.0 or later), it also lists sessions in the same project on a teammate's computer.
• Notes and handoffs between sessions. An agent can leave a note for another session, even one that has closed. The note arrives at that session's next KLYPIX action, so you are not the one copying it across. When a session stops before its work is done, the next session on this computer is shown what it was doing, and a handoff card in the brain carries the next steps through Git.
• A git guard for a shared checkout (Claude Code). When several sessions share one checkout, a git command that would sweep another live session's uncommitted work into your commit is stopped. A command that would throw work away saves a rescue copy first, then asks you. It covers git commands run through Claude Code's tools, on one computer.
• Lessons that catch the repeat mistake. A lesson the brain recorded can become a project rule that a person approves: a check of the diff, with no AI at check time. A rule warns when a session plans its files, while it edits and at commit. Only a rule the person approves as blocking stops the work: Claude Code before it writes the forbidden line (Codex is warned), and an opt-in git hook at commit, for any tool or person. Rules check the diff; they do not run your tests.
• A file you own. The brain is one .klypix file in your repo: a plain ZIP, versioned with Git. The engine is Apache-2.0, runs on your machine, and works without the KLYPIX app or an account. Brain data stays in your files; your agent's model provider still receives what the agent reads.

Hosts

How deep the integration goes depends on the host. The full table has the details.

| Host | What it gets | Set up by | |---|---|---| | Claude Code | Six lifecycle hooks (1.105.0 and later): a brief at session start, context on each prompt, automatic capture at turn end, presence and the git guard | install | | Codex | Native MCP tools, presence and brain_sync; optional hooks with --codex-hooks. No automatic capture | install | | Cursor, Cline, VS Code (Copilot / Continue), Gemini CLI, Antigravity | MCP config and an always-on rules file. The agent calls brain_sync and brain_note itself | install, for the editors it finds, or link | | Windsurf, Aider | A rules file. Windsurf uses its own global MCP config; Aider uses the command line | link | | Claude Desktop | A one-time config entry | The KLYPIX app's Settings, or by hand | | Claude, as a plugin | One pinned version, keyword search, no hooks | klypix-plugin |

klypix-mcp has 27 MCP tools on Linux and macOS and 28 on Windows, where show_in_klypix is added. npx klypix-mcp doctor shows the count for your install.

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.

KLYPIX is a portable project workspace with a shared brain. This repository is its local MCP server. The optional Windows workspace lets people inspect the same brain beside their files; app-based sharing has its own cloud path (see Security and permissions). For the Projects & Ideas path, saved project materials in ChatGPT or Claude chat, follow Save project materials and use them with your assistant. That uses KLYPIX's separate hosted connection for the spaces you authorize; installing this local server does not set it up.

Guides: shared project memory setup · memory tools comparison (it links each tool's official documentation and says that KLYPIX wrote it) · klypix.com/klypix-mcp

Contents

• Start: The problem · 60 seconds: two agents, one project · Quick start · Your first decision and correction
• Reference: How the brain works · Supported hosts · Running as a Claude plugin · Task briefing · Capture and corrections · Project rules · Presence and task intent · Overlap warnings · Teammates on other computers · Handoffs and messages · Evidence-gated completion · Human control in KLYPIX · Measure it yourself · Git and concurrency · The git guard for a shared checkout · The command line · The verbs · One file you can hold · Use it as a library · A2A · Updates · Security and permissions · Current limitations · Numbers and methodology · Uninstall
• Contributing · Why this exists · Licence

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. Context saved in one tool may be missing from the next:

• A new session misses a prior decision, and you explain the same architecture again.
• A decision captured only in a Claude conversation is unavailable to your Codex session.
• 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; the reasons behind a change still need to be recorded.

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

60 seconds: two agents, one project

Real output, not a mockup: both panes run a real MCP client against this server (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).

Illustrative calls and responses: replace /absolute/path/to/project with the same project root in both sessions (for example, C:/work/api on Windows).

Session A — Claude Code, in your repo:

brain_sync { project: "/absolute/path/to/project", phase: "start",
             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:

brain_sync { project: "/absolute/path/to/project", phase: "start",
             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:

brain_challenge { claim: "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:

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:

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:

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:

Illustrative output; detected editors, file counts, tool counts and timings vary with the machine and installed version:

  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 six lifecycle hooks (five before 1.105.0) 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:

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:

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.

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 — the KLYPIX app does it in one click (Save canvas as project brain), or create_canvas makes one from any agent.

Your first decision and correction

After installation, reopen your coding tool or reconnect its MCP server, and allow the KLYPIX tools if your host asks. Run npx klypix-mcp doctor in the project to inspect the installation; a clean config report does not prove that your host has loaded the tools.

Try the following in a disposable trial project, or replace the example decision with a real one before saving it. These are MCP tool calls for your agent, not shell commands. Replace /absolute/path/to/project with your project root throughout. The files: [] scope means this trial does not plan source-code edits.

1. Record a decision and its reason. Ask your agent to call:

   brain_sync { project: "/absolute/path/to/project", phase: "start",
                intent: "Record the trial storage decision", files: [] }
   brain_note { area: "Storage",
                text: "Use SQLite for the trial project database because this prototype runs on one machine." }
   brain_sync { project: "/absolute/path/to/project", phase: "complete" }

2. Open a fresh session in the same project, optionally in a different supported coding tool. Ask it to retrieve the decision rather than infer the answer from your code:

   brain_sync { project: "/absolute/path/to/project", phase: "start",
                intent: "Review the trial storage decision", files: [] }
   brain_ask { question: "Which database does the trial project use, and why?" }

   Check that the returned card contains SQLite and the one-machine rationale. If the tool is missing, reconnect the host and check the host integration table. If the card is missing, confirm both sessions used the same project and that brain_note reported a successful capture. A fresh brain only knows what has been recorded.

3. Change the trial decision explicitly, then ask again:

   brain_note { area: "Storage",
                text: "CORRECTION: Use PostgreSQL instead of SQLite for the trial project database because the trial now needs concurrent writes from several machines." }
   brain_ask { question: "Which database does the trial project use now, and why?" }
   brain_sync { project: "/absolute/path/to/project", phase: "complete" }

   Inspect the returned source cards: PostgreSQL should be the current decision, with SQLite retained as superseded history. Confirm that the correction names the earlier decision; a correction cue alone is not a guarantee of a match. This small trial checks your capture and recall path. It does not establish retrieval quality for a larger brain or prove host automation.

For a team on different machines, follow the Git sharing steps and install in each clone. Standalone live presence and file-overlap warnings stay local to one machine and OS user; with KLYPIX network on each computer, they also cover teammates' sessions in the same project. Keep approved architecture records and stable conventions alongside the brain.

Reference

Everything below is reference: how each part works, what it writes, and where it stops. The contents list above links to each section.

How the brain works

The difference from a folder of notes is not the shape — it is that this memory is a mechanism, not a filing convention.

• Decisions have a lifecycle. A new decision that contradicts an old one supersedes it. The stale card is archived with an arrow and a date, never deleted, and later answers surface the correction rather than the corpse. If a later decision returns to an earlier superseded stance, high-confidence lineage leaves a dated re-adopts stamp on the new card plus an earlier→current edge; the original A→B→C history remains intact.
• Corrections are explicit, not guessed. Supersession fires on an UPPERCASE correction cue or an explicit edge. brain_reconcile only proposes stale-vs-correction pairs for a human to confirm.
• Cards can cite the code they were decided against. An ev: anchor records a file:line plus the git blob OID at capture time, so the engine can flag a card whose cited code has since moved on. It detects that the code changed — never that the claim became false.
• Position means something. Drag a card into the 📌 Focus area and it leads every future session's brief. That is brief priority, not a retrieval-ranking boost.
• You can ask what the project believed then. brain_ask with as_of: 2026-03-01 reweights ranking by card lifecycle dates, so corrections made later do not leak backwards.
• Retrieval is local. With the on-device model ("search by meaning"), brain_ask and search_all_brains use BGE semantic ranking with lexical help for exact identifiers, paths, and versions — still entirely on your machine. Without it, retrieval is keyword-only. The previous cross-encoder is available for experiments with KLYPIX_RERANK=1, but is off by default because it reduced precision and added latency on the frozen human-paraphrase evaluation.
• Search by meaning is installed for you (1.97). npx klypix-mcp install run by a person in a terminal installs it: about 150 MB to download once, about 110 MB on disk after the files Node never loads are removed. Skip it with --no-semantic (or KLYPIX_SEMANTIC=0). Installs with no terminal — CI, scripts, an AI agent running the install — get it only with --semantic. The Claude plugin never downloads it. Measured on the frozen 102-question set: the right card in the top 5 for 54 questions with it, 19 without.
• Preparing a brain never makes a question wait. Each card is turned into a meaning vector once (about 45 ms a card on a laptop CPU, one card at a time, ~305 MB peak), newest cards first, by a low-priority background job that saves as it goes. A question on a brain that is not ready yet answers right away from what is ready plus keywords, and says how far along the preparation is ("Getting this brain ready for search by meaning: 900 of 3,670 cards so far, about 5 min left"). After that, only new or edited cards are prepared.

Bounded semantic-memory runtime

Long-lived MCP and A2A workers use the bounded semantic-memory runtime by default. Models load only when semantic work is requested, native inference is serialized per process, embedding work is split into small batches, and temporary tensors are released after use. Loaded models retire after an idle interval and transparently reload on the next semantic request, so warm queries stay fast without permanently pinning native model memory. These controls change the resource lifecycle only; brain cards, project coordination, and the on-disk brain format are unchanged.

The previous runtime remains available as an emergency rollback. Set KLYPIX_SEMANTIC_MEMORY_MODE=legacy in the MCP server environment and reconnect or restart the host. This restores eager model prewarming and the previous inference path without migrating or deleting brain data. Remove the variable (or set it to bounded) to return to the bounded runtime.

Run the deterministic lifecycle tests with npm run test:memory. For an opt-in real-model soak against a disposable or backed-up brain, set KLYPIX_MEMORY_SOAK_BRAIN to its path and run npm run test:memory:soak.

For process-level attribution, run npx klypix-mcp runtime (or add --json; --watch 30 samples every 30 seconds). It reports KLYPIX workers, supervisors, and legacy launcher overhead separately, excludes the owning IDE/chat application's RAM, redacts command-line secrets, and never opens a brain or terminates a process. Multiple processes under one host are reported as parallel sessions, not called duplicates without an authoritative logical-session receipt.

Project Map: current structure beside project understanding

If the project contains a compatible NetworkX node-link graph.json, agents can ask for bounded code-structure evidence and current brain context in one read-only call:

project_map_context {
  "question": "what owns refresh-token rotation?",
  "graph_path": "graphify-out/graph.json"
}

Use compare_to with another project-relative graph artifact to add exact total node/edge deltas and additions/removals from the two bounded query neighborhoods. Both paths are confined to the declared project root; unsafe source paths are withheld; large or unsupported artifacts are rejected. When a returned brain card names an exact mapped source path, the structured response also includes a review-only evidence-link proposal. It never promotes similarity into truth and never writes graph facts or links into brain.klypix.

Graphify is the first compatible producer. KLYPIX reads artifacts that users generate separately; it does not bundle, install, or run Graphify and does not imply a partnership. A compatible generic graph.json works through the same provider-neutral boundary.

For a reproducible map artifact on every pull request and main-branch push, install the shipped read-only workflow into a Git checkout:

npx -y -p klypix-mcp klypix-project-map setup-github /path/to/project

The command refuses to overwrite an existing workflow unless --force is explicit. The installed workflow has contents: read, pins every action by commit SHA, pins graphifyy==0.9.33, validates the graph contract, and uploads graphify-out/ as a 14-day build artifact. This is opt-in CI code: the local MCP tool still never installs or launches Graphify.

Supported hosts and their integration level

Levels are honest. Only the config-writing side is tested for the link hosts; their host-side behaviour is unverified.

| Host | Level | Wired by | Brief into context | Decision capture | Live presence | |---|---|---|---|---|---| | Claude Code | Full automatic (6 lifecycle hooks since 1.105.0) | install | Automatic at session start, task-ranked retrieval per prompt | Automatic at turn end | Yes | | Codex | Native MCP + presence + Context Gateway; optional --codex-hooks | install | Via brain_sync; per-prompt injection only with --codex-hooks | Explicit only (brain_note) — never automatic | Yes | | Cursor | MCP config + always-on rules file | link | Model must call brain_sync | Model must call brain_note | For the MCP connection | | Cline | MCP config + always-on rules file | link | Model must call brain_sync | Model must call brain_note | For the MCP connection | | VS Code (Copilot / Continue) | MCP config + instructions file | link | Model must call brain_sync | Model must call brain_note | For the MCP connection | | Gemini CLI / Antigravity | MCP config + always-on rules file | link | Model must call brain_sync | Model must call brain_note | For the MCP connection | | Windsurf | Rules file only | link | Reaches the tools through Windsurf's own global MCP config | Model must call brain_note | Via its own MCP config | | Aider | Rules file only (no MCP) | link | CLI path: npx -y -p klypix-mcp klypix-read | CLI path: npx -y -p klypix-mcp klypix-append | — | | Claude Desktop | One-time config: KLYPIX's Settings button, or a manual edit | KLYPIX app or you | Model must call brain_sync | Model must call brain_note | For the MCP connection |

install and link are different things and are not interchangeable: install sets up the machine engine and hooks, then wires supported hosts detected for this project (see Quick start). link is the explicit per-project repair/projection path for all 14 managed files, regardless of which hosts are installed.

Claude Desktop — in the KLYPIX desktop app, Settings → Project → Connect Claude Desktop writes this entry for you; or add it to claude_desktop_config.json by hand. Either way it needs Node.js on the PC, and Claude Desktop must be quit completely (tray icon → Quit) and reopened before it lists the tools:

{
  "mcpServers": {
    "klypix": {
      "command": "npx",
      "args": ["-y", "klypix-mcp", "--vault", "/absolute/path/to/canvases"]
    }
  }
}

Running as a Claude plugin

The KLYPIX Claude plugin starts this server as npx -y klypix-mcp@<version>, with the version its .claude-plugin/plugin.json names: one exact version, never a range or latest. It sets three variables: KLYPIX_PLUGIN=1, KLYPIX_PLUGIN_DATA=${CLAUDE_PLUGIN_DATA} and KLYPIX_VAULT=${CLAUDE_PROJECT_DIR}. KLYPIX_PLUGIN=1 turns on plugin mode, which changes how the MCP server behaves and nothing else. Every npx klypix-mcp command (install, link, doctor, sessions and the rest) works exactly as described elsewhere in this README. Only KLYPIX_PLUGIN=1 turns plugin mode on; CLAUDE_PLUGIN_ROOT on its own does not.

What plugin mode never does

• Update itself. It never asks npm for a newer release and never installs one, whatever KLYPIX_AUTO_UPDATE is set to. You run the version the plugin pins, and a newer version reaches you only in a new plugin release.
• Run code from outside the package. It runs only the worker inside the pinned package. It never starts or switches to the copy that npx klypix-mcp install puts in ~/.claude/project-brain, and it never loads the optional on-device semantic model from that folder. Search is keyword-only, so it never downloads model weights.
• Write project config files. It never creates or rewrites rules files, editor MCP configs (.mcp.json, .cursor/, .codex/config.toml and the rest) or the AGENTS.md brief block, in this project or any other. Outside plugin mode, brain_sync and the updater do write these files; Security and permissions explains when.
• Change Claude's settings. It never writes ~/.claude/settings.json, hooks, permissions or any other host configuration.
• Collect data or read credentials. It sends no telemetry or usage data, reads no API keys or account tokens, and opens no network port. The one token it reads is the local bridge token the KLYPIX app writes for AI tools while it runs (below); it is never logged or returned.

Network. Plugin mode makes two kinds of request, and both go to the public npm registry. The first is npx downloading the pinned package when the plugin starts the server. The second is one npm view klypix-mcp version, and it runs only when an agent calls brain_doctor with check_npm: true. There are no other requests.

Programs it runs on your computer. Read-only git commands in your project (current branch, tags, log) for coordination and release checks. Also brain_reopen, described at the end of this section. And on Windows, show_in_klypix with bring_to_front: true while KLYPIX is closed asks Windows to open that canvas file in KLYPIX (PowerShell Start-Process), at most once every 30 seconds; it never does so while KLYPIX is running.

The KLYPIX app, when it is running (local, not the network). On Windows, a tool call that needs the KLYPIX app (App mode, under Human control in Klypix) talks to the app over a local named pipe: inter-process communication on this PC. Plugin mode allows it, exactly as outside plugin mode. Nothing connects when the server starts; on such a call it reads %APPDATA%\klypix\agent-bridge\endpoint.json and the bridge token KLYPIX writes in %LOCALAPPDATA%\klypix\agent-bridge. With KLYPIX closed, or its AI tools on this PC switch off, nothing connects at all.

What it reads. In your project: brain.klypix, the .klypix canvases, the version field of package.json and your git tags. On your computer: the coordination files in the table below. If the KLYPIX desktop app is installed, it also reads the app's data folder (%APPDATA%\klypix), read-only, to see whether the app is running, which canvases it has open, and the readings it saved on cards, and, on a call that needs the running app, the app's bridge token (above). It never reads chat history, transcripts or Claude's memory.

What it writes, and where

| Where | What | Why | |---|---|---| | Your project | Only what a tool call asks for: brain.klypix (brain_note and the other brain tools), canvases (create_canvas, add_to_canvas), klypix-map/graph.json when project_map_scan is called, .klypix/claims/<owner>.json when brain_sync is asked to publish a release claim, and .klypix/rules.json when brain_rules adds, approves or retires a rule. Only when you run npx klypix-mcp check --install-hook: a marked block in .git/hooks/pre-commit, pre-push and post-commit; npx klypix-mcp rules allow keeps its one-hour exception in .git/klypix-rules-allow.json. During a brain write it holds .claude/brain-capture.lock, creating the .claude/ folder if the project has none. The lock file is deleted after the write; the folder stays. Creating a canvas briefly holds .klypix-create.lock in the folder. | The KLYPIX app and every other session that writes the brain use the same locks, so two writers never overwrite each other. | | The plugin's data folder (KLYPIX_PLUGIN_DATA) | Connection receipts (.supervisors/), the running-server heartbeat (.running-servers.json), the list of projects whose brains you used (registry.json, which search_all_brains reads), and the last version and git tag seen in each project (ship-observations/). Also extracted/: copies of the PDFs, Office and other files read_card_contents hands to your AI tool as a local path, taken from the canvas you asked about. | Only this server uses these files. If KLYPIX_PLUGIN_DATA is not set, or still contains a ${...} that was never filled in, it uses CLAUDE_PLUGIN_DATA. If neither is usable, the files go in ~/.claude/project-brain, except extracted/, which then goes in <system temp>/klypix-mcp/extracted (where it always goes outside plugin mode). | | ~/.claude/project-brain (shared) | Presence lanes (sessions/), write locks (locks/), restore points (history/), and small records built from your brain: .capture-gap.json, and enrichment/, provenance/, .brief-cache-* and .guards-* when the tools that use them run. rules/ counts how often each project rule fired, blocked or was overridden on this computer. | Your other KLYPIX sessions on this computer (Claude Code, Codex, Cursor, the app) use the same files on purpose. Through them, a plugin session and a terminal session on the same project see each other, get warnings when they plan to edit the same files, and pass notes. Restore points are kept here so that npx klypix-mcp brain-history can still undo a brain write after you remove the plugin. |

brain_reopen. Sometimes a session leaves a note for another session that has already closed. An agent can then call brain_reopen, and KLYPIX asks you first: in chat with Reopen and Not now buttons, or in a small dialog (PowerShell on Windows, osascript on macOS, zenity or kdialog on Linux). Only if you choose Reopen does it open a new, visible terminal that runs the app's own resume command, claude --resume <id> or codex resume <id>. Reopen on your OK has the details.

After you uninstall the plugin. Claude Code removes the plugin and deletes its data folder. These stay: your brain and canvases, which belong to you; any .claude/ folder a brain write created in a project; and the presence lanes, write locks and restore points in ~/.claude/project-brain. Other KLYPIX tools on this computer share that folder. If you use none, you can delete it.

Task briefing

Every Claude Code session starts already knowing the project: a bounded brief of at most 2KB in context, with the full brief written to disk for when broad history or status work needs it.

Every other host gets a bounded ~2.8KB task capsule from one brain_sync call, plus a compact always-loaded AGENTS.md block that tells the agent to make that call at task start, when scope changes, and on completion. The gateway capsule is lexical-fast by design. A newly captured open gap can claim a labeled RECENT OPEN slot only after clearing the normal lexical-relevance floor, so fresh relevant findings are not crowded out by older area vocabulary. When the call declares files, the lessons that name those files come first, under "Lessons for your files": at most four, ranked exact path, then file name, glob and folder. The Claude Code brief does the same for the files the checkout is changing (uncommitted, and the last three commits), then lists the newest.

Briefs are not injected automatically on Cursor, Cline, Copilot, Gemini CLI or Antigravity — there are no lifecycle hooks on those hosts.

The live projection — the file the agent obeys

The coordination bench showed that an agent trusts the instruction file it was launched with over anything a tool or hook tells it, and that each host reads a different surface. So the brain's state is projected into those files, in two halves:

• Committed, from the brain: the compact brief block in AGENTS.md (standing rules, corrections, open handoff cards), refreshed by the Claude Code Stop hook only when its content changed, so diffs stay quiet.
• Machine-local, from the lane (klypix-mcp 1.104.0): which sessions are live on this PC and which files they hold, the work a stopped session left, and the evidence beside every "keep off this file" note — written at session start and at every Stop by the Claude Code and Codex hooks into CLAUDE.local.md at the project root (Claude Code loads it beside CLAUDE.md; KLYPIX keeps it out of git through .git/info/exclude, never a committed file) and into one section per project of the Codex global instructions file (~/.codex/AGENTS.override.md when you have one, else ~/.codex/AGENTS.md). A project-level AGENTS.override.md is never written: Codex loads one file per directory, so it would hide your AGENTS.md.

The block is a snapshot and says so: bounded to about 2.4KB, rewritten only when its content changed (the time stamp alone never causes a write), with the keep-off evidence kept first when the budget bites, and "nothing live" written in words so an older snapshot never stands. It holds the same strings the hooks print, so the file and the session context cannot disagree. Sections for projects not touched in a day are pruned from the Codex file, at most eight are kept, and uninstall unlink strips the block (deleting CLAUDE.local.md only when nothing else is in it). brain_sync remains the live source; the block tells the agent to call it.

Capture and corrections

brain_note accepts structured supporting references and inert verification text:

{
  "text": "Retry failed uploads with a bounded backoff to preserve queued work.",
  "area": "Storage",
  "evidence": [{ "kind": "file", "ref": "src/uploads.mjs:42" }],
  "verify": "node test/uploads.mjs"
}

File references must stay inside the project. The capture records a fingerprint of the working file and, when available, the repository HEAD revision. An unchanged fingerprint means source unchanged, not that the remembered claim is correct or that tests passed. Dirty working files are fingerprinted as they are; HEAD alone does not describe those bytes. Read results distinguish changed, missing, and unverified sources. External references (pr, url, commit, run) are retained without fetching or verifying them. verify is shown as recorded text and never executed. Optional verifiedAt is explicitly caller-reported.

On an amendment (marker: "~"), omitted metadata is preserved; evidence: [] and verify: "" clear obsolete metadata. A resolve (✓) archives existing evidence; attach new evidence with a milestone and closes, or amend before resolving. The CLI accepts the same JSON on stdin, or --evidence '<JSON array>' and --verify '<text>'.

On Claude Code, decisions are captured automatically at turn end from inline 🧠 BRAIN [Area]: markers in the transcript, deduped, under a capture lock.

A marker can end with optional suffixes, in any order: closes: <card title or [[wikilink]]>, ev: <file[:line]>, PR#<n>, verify: <command>, q: <the question this answers?> and rule: <glob>[,<glob>] never "<text>" (or never /<regex>/, must "<text>", listed-in <file>[,<file>], keep-eol, costly). They count only as one run at the end of the line, written lowercase as key: value, and each value must have its key's shape: references for ev:, a command for verify:, a question (question word first, ? last) for q:. Anything else is kept as card text, so "a Q: and A: layout", "the ev: field" or "every agent verify: the tag" never cuts a note short. A malformed segment after a well-formed one also stays in the text, and the other suffixes still count; the hook tells the agent on its next prompt. On ✓ and ~ markers a closes: is plain text, because those markers close nothing. A closes: that will not act keeps the sentence as written: it names no live card, or it names more than four. A closes: that does not come after the end of a sentence, a [[wikilink]] or another suffix closes only a card it names by title. One whose named card is already closed closes nothing else. A ~ update too thin to replace its card (fewer than six content words and under half the card's) is appended to that card as a dated (~ amended …) line instead. The card keeps its date, colour and probe, and previews show the newest amendment first. The correction lands and nothing is lost.

A rule: suffix makes a new lesson (a decision, + or !) rule-ready. Its globs must name files tracked in the repository and a /regex/ must compile; the rule lands as a visible ⚙ rule candidate: line on a 🛠️ card, and brain_rules propose reads it before any prose. It checks nothing until a person approves the rule. A rule that fails those checks is not recorded, the lesson is, and the hook says why on the next prompt. brain_note takes the same suffix at the end of its text.

The Stop hook reads the whole transcript every time, so a ~ or ✓ line applies once. A marker that an older hook (1.85 or 1.86.0) already captured is not captured again after an upgrade. If 1.86.0 cut the note short, the stub is restored to the full text in place. When a marker does not do what it says, the next prompt tells the agent. A receipt left by a session that has ended goes to the next session that starts in the project.

On every other host, capture is explicit: brain_note runs the same capture engine as the hooks — dedup, supersession, round-trip re-adoption receipts, ✓ resolve, ~ update in place, + skill, closes: — and stamps which agent wrote the card. A ✓ question preference ranks only candidates that already clear raw lexical overlap and two subject-identity anchors; generic lifecycle wording cannot turn weak overlap into a closure. (If you install the git commit hook from the KLYPIX app or run npx klypix-mcp git-hook install, commit messages also capture automatically for any agent.)

brain_challenge is the other direction: propose a decision and the brain answers with receipts — prior decisions that deterministically contradict it, standing rules that dispute it, and approaches tried and reversed, flagged when a different agent wrote them. Evidence is deterministic only (explicit correction cues, opposite-polarity pairs), never mere topical similarity. Silence means no contradiction signal was found — not verified consistency. A memory that cannot disagree with you is flattery.

Project rules: lessons that stop the repeat

Some lessons can be checked in a diff: every new route must also be in the route list, tests in this folder must import shared code relatively, this file's line endings must not change. brain_rules turns those lessons into rules in .klypix/rules.json, each citing the card it came from. A person approves each rule with a code only they can print (npx klypix-mcp rules code promote <ids>). Until then the rule is a candidate and checks nothing.

An active rule runs in three places: brain_sync names the rules for a session's files, the edit hook reports findings to Claude Code and Codex as they edit, and the opt-in git hooks (npx klypix-mcp check --install-hook) print them at commit and push. Rules warn by default. A rule the person approves with --block stops the commit or push for any tool or person, and stops Claude Code before it writes a forbidden line; Codex is only warned, because its hooks cannot deny. A check is glob, regex and line-ending work over the diff: it takes milliseconds, runs offline and uses no model. Overrides, bypasses and false alarms are recorded in the brain, and npx klypix-mcp rules shows each rule's blocks, overrides and false alarms.

How to write, approve and retire rules: docs/brain-rules.md. To see what a set of rules would have flagged on a repository's own history, scripts/brain-rules-proof.mjs replays them over its pull requests and failed Actions logs, with what those runs cost. A walk-through for teams: Stop AI agents repeating the same mistakes.

Presence and task intent

An active session means an authorized MCP connection or host lifecycle adapter that heartbeated within the TTL. A row in a recent-chat list is history, not presence.

Each MCP connection registers itself at initialization and removes itself on disconnect; the TTL covers crashes. Optional host adapters merge into that same logical session rather than double-counting it, enrich it with intent and files, and remove only their own channel. Sessions that never declared a task are still counted, but are shown separately as scope-unknown rather than padding the peer list.

Future hosts get baseline support merely by connecting the MCP server. A deeper adapter can import klypix-mcp/presence and map lifecycle events onto upsertSession, removeSession, peekMessages and receiveMessages. The shared contract accepts id, client, surface, model, branch, intent, touched files, and adapter channel.

Overlap warnings

brain_sync reports three kinds of overlap with other live sessions on the same brain:

• Same file. Both sessions declared, or were observed editing, the same path. You see the peer, its task and the paths in common, and a one-time alert is queued to whichever session got there first, so a late arrival is not the only one who knows.
• Would conflict at merge. The two sessions are on different branches, and a test merge of the two branch tips (git merge-tree, git 2.38 or newer) conflicts in named files, even though no declared file overlaps. This sees committed work only: an uncommitted edit is invisible to git. It also gets a one-time alert. Files the brain tooling regenerates on every branch (AGENTS.md, rule files, .mcp.json, brain.klypix) are not counted.
• Same folder (advisory). Both sessions work in one folder with no file in common yet. No alert is sent. A folder that at least three sessions, and more than half of them, touch is treated as noise and not reported.

This warns. It does not prevent. Nothing blocks an edit. A session that never declared its files and was never observed editing is invisible to the file and folder checks.

Teammates on other computers (KLYPIX network)

Presence, overlap warnings and notes are local to one computer by default. Since klypix-mcp 1.106.0 they also reach a teammate's computer when KLYPIX network, a small separate background program, is installed on both computers (curl -fsSL https://klypix.com/network/install.sh | sh, or irm https://klypix.com/network/install.ps1 | iex on Windows):

• brain_sync also lists agent sessions in the same project on a teammate's computer, with their one-line task and declared files, and gives the same exact-file overlap warning it gives for a session on this machine.
• brain_message reaches those sessions too. Their ids start with net:. A note to every session goes to this machine's sessions and theirs.

What leaves the computer: the project key (a hash of the git remote), the one-line task, repository-relative file paths, and the text of a note you send to a session there. Cards, files, diffs and screens do not travel this way; the brain itself still moves through Git. There is no read receipt and no result reconciliation across computers. The warnings are advisory, exactly as on one computer.

Without the program nothing changes. It is off with KLYPIX_NETWORK=0 and in plugin mode. No two-computer test run is published for it yet.

Handoffs and messages

brain_message leaves one-time coordination notes for other sessions — live, idle, or recently closed. Address a session by id: a live session gets the note on its next action; a session KLYPIX has identified before that is not on the lane now (closed, or quiet) still receives a directed note the moment it next acts — a directed note is kept 7 days, and the sender is told it is queued, not delivered. That is what stops the human from being the courier between two agents: the standing rule every host receives is that a message it would otherwise ask the person to relay or paste is sent this way instead. Nothing here starts or wakes a session on its own — the note waits until a person opens it, and the person decides when that is (see Reopen on your OK below). A supported KLYPIX action offers the note in model-visible context; the next independent supported action replays it and records an acknowledgement. That acknowledgement proves only that a later action followed the offer — never that a person read it or that an agent acted on it. The note keeps replaying until the receiving model calls brain_message_receipt with the exact message id and per-recipient offer token; only that token-bound action records consumed. Pending, offered, and acknowledged notes survive reconnects. Expiry or bounded-capacity eviction records a failed per-recipient receipt instead of silently looking delivered. The send-time audience is fixed, unresolved targeted sends fail closed, the core lane is machine-local, a note to every session expires after 24 hours and a directed note after 7 days, and notes are never written into the brain.

Reopen on your OK

A note to a session that has closed would otherwise wait until someone happens to open that session again. When the person wants it handled sooner, the sending agent calls brain_reopen, and KLYPIX asks the person — an in-chat Reopen / Not now prompt in apps that support MCP elicitation (Claude Code, Codex), otherwise a small native dialog. Only on Reopen does KLYPIX open that Claude Code or Codex session in a new, visible terminal, in the folder it worked in, with the host's own resume command (claude --resume <id>, codex resume <id>); the session receives the waiting note at its first action and the sender sees the receipt as usual.

• The person decides, never a model: the answer comes from the app's prompt or KLYPIX's own dialog, which no agent can click. With neither available, nothing opens and the person is given the command to run.
• Only a session with a note addressed to it is reopened — KLYPIX reopens a conversation so a note can reach it; it does not start, route or supervise agents.
• The first prompt the reopened session gets is fixed text that tells it to collect the note; the note itself arrives through the labelled message channel as information from another session, never typed in as if the person had said it. The sender's session identity never leaks into it.
• Not now is remembered: the same session is not offered again for a while, and a double click cannot open two windows.
• From a terminal: npx klypix-mcp sessions lists this project's closed sessions and the notes waiting for them; npx klypix-mcp sessions reopen <id> reopens one (--quiet lets it wait for you instead of starting on the note).

Session handoff — continue in the next session, with any agent

The case this exists for: a Claude Code session stops at its usage limit in the middle of a task, and the person opens Codex (or a fresh Claude Code) and says continue. Until 1.99.0 the only handoff was whatever the person pasted. Now there are two layers, and the person does not have to ask for either.

Automatic — whichever agent stopped. Each session's last state is recorded on the lane that already remembers sessions for two weeks, by whatever that host offers:

| Host | Recorded automatically | |---|---| | Claude Code (hooks) | last prompt, the tail of the last reply, files edited, its own commits | | Codex (hooks) | last prompt, the tail of the last reply, files edited, its own commits | | Any MCP host — Cursor, VS Code, Windsurf, Gemini CLI, … | the task and files it declared with brain_sync |

Own commits are the shas that session's git commit printed, never a branch range, because twenty sessions can share one checkout. A session is listed when it stopped in the last 24 hours without completing its task — quiet for ten minutes, or closed — and left a record. A session that recorded nothing is never listed, so finished chats do not pile up.

The next session on the project, in any agent, sees ⏸️ Work other sessions may have left unfinished at its first brain_sync when its task is to continue something ("continue what Codex was doing on the invoice" puts that session first) or touches a file one of them touched. It sees the same list at session start. Each record carries its status, files, commits, last words and resume command. It says, in the text and in the JSON (state, working:false, holdsFiles:false), that the session is not running, holds no claim on any file, and that a "do not touch" note it left no longer applies: the list is history, not a lock. The agent takes a record over with brain_handoff {action:"take", session:"<id>"} so peers see it is taken, then marks it done. This layer is machine-local, like the rest of the lane.

Deliberate. When a session knows it is stopping — the person asks for a handoff, the context or usage limit is near, the day ends, it is blocked, it is switching tool — it calls brain_handoff {action:"write"} with the task, what is done, what is next in order, the files and how to verify. That becomes a 🤝 HANDOFF card in the project brain: an open card the person can see and correct on the canvas, with the files as evidence anchors, that travels with the repo and syncs like every other card. It leads the session-start brief and the brain_sync start response until a session takes it ({action:"take", id}) and finishes it ({action:"done", id}, which archives it). A later handoff can name the earlier one it continues. The per-prompt hook nudges the agent to write one when the person says handoff or names the limit.

Drafted by KLYPIX — when the session never got to write one. A usage limit, a crash or a closed window leaves no time for brain_handoff. Since 1.103.0 the brain writes the card itself: at the next brain_sync start or brain_handoff list of any session, a record that qualifies — the session is closed or quiet for 30 minutes, left real work (its own commits, or touched files and a reply tail), has no card and no taker, and its task was a human's, not an app's — becomes a 🤝 HANDOFF card on that session's behalf, reason interrupted. The card says Drafted: by KLYPIX on its own line, lists only what git proved under Done, tells the reader to confirm the state with git status before touching anything, and carries the session's last words verbatim. The record and every list say the session wrote none. If the session resumes and completes its task, the drafted card is archived at the next pass. Three drafts per pass at most; a draft can never fail the sync that triggered it.

Conversation coverage. A card and the automatic reply tail can miss a later request. Taking a card now checks its source conversation and reports needs-review, reviewed, or unknown. brain_handoff {action:"review", id} returns paginated Claude Code or Codex conversation turns, including user requests with no reply. Follow nextCursor with the returned revision; after reading every page, acknowledge the final reviewToken with a summary of completed and still-pending requests. Session-only takeovers use review with session to create a reviewable draft first. The first review covers the whole conversation, including requests that predate the card; changed source bytes invalidate the review and require another pass. The saved review is an agent attestation, not proof of task completion. It never closes work. Transcripts stay on this machine and are read only from the supported hosts' transcript folders. Missing, malformed, ambiguous, oversized, or unsupported sources report unknown; an attachment placeholder requires checking the original media. The reader is bounded to 128 MiB per transcript, 16 MiB per JSONL record, 8 MiB of conversation text, and 12,000 discovery entries. A limit never silently drops turns or certifies coverage. Reconcile the card's Next list with the conversation and repository evidence before continuing.

Host coverage (1.108.0). The shared handoff card works independently of the agent brand. Conversation recovery has separate coverage:

| Source | Evidence available | | --- | --- | | Claude Code, Codex | Native local transcript readers | | Gemini CLI | Native legacy ConversationRecord JSON; JSONL mutation journals currently return UNKNOWN | | Antigravity, Cursor, Cline, Roo Code, Kilo Code, GitHub Copilot, Continue, Windsurf, OpenCode, custom MCP clients | Host-neutral capture through the same MCP action; no native history reader claimed | | CLI-only integrations such as Aider | Shared handoff cards; capture requires an MCP bridge calling this action |

On a host without a native reader, preserve requests as they arrive with brain_handoff {action:"capture", turns:[{id:"stable-turn-id", role:"user", at:1792860000000, text:"Observed request"}]}. Use the actual known timestamp (milliseconds), stable ids for retries, and only text actually observed. Capture assistant replies too. Do not manufacture missing history or timestamps. The server binds capture to the connected session and project; callers cannot supply another session identity or a file path. Later sessions use the same review workflow. New captured turns invalidate prior review tokens. Repeated identical turns are deduplicated; conflicting reuse of an id is refused.

Capture is an explicit agent/tool action, not automatic access to an IDE's private chat store. The result always identifies captured-only coverage and says full host history is UNKNOWN, even after review. It cannot recover a request that was never captured. Host-name regression fixtures verify the shared protocol, not end-to-end operation inside those applications. Captured text stays outside the brain in ~/.claude/project-brain/handoff-captures, keyed by project and session. It is not synced with the card and has no automatic expiry; local removal makes coverage unavailable. Limits are 30 turns per call, 24,000 characters per turn and 8 MiB per journal. Gemini discovery has a 128 MiB aggregate read budget and rejects ambiguous sources.

Durable decisions still go in the brain as cards — a handoff is the one card about work in flight, and it closes when the work lands.

Evidence-gated completion

When a task publishes a quantified or otherwise machine-checkable claim, it can attach one or more versioned result manifests to brain_sync { phase: "complete" }. Each manifest binds the claim to a report hash, producer/run provenance, the exact declared task scope, material artifact hashes, evaluation outputs, public metric wording, input/configuration fingerprints, and named metrics with counts and tolerances. Matching peer evidence is recorded as corroboration; conflicting or incomparable evidence returns needs-reconciliation and keeps the task scope active.

The gate fails closed. Once a task submits result evidence, it cannot bypass an invalid or conflicting result by retrying completion without the manifest, and that obligation survives worker restart, hibernation, and transparent hot-swap. A fresh phase: "start" is the explicit boundary for a new task. The strict schema and reusable validator are exported as klypix-mcp/result-reconcile. Schema-v2 receipts can be converted into commit-bound publication evidence and independently checked with klypix-mcp/release-evidence; legacy schema-v1 results remain usable for coordination but cannot authorize publication.

Human control in Klypix

Not a second brain. A shared one.

A brain nobody can inspect is a database with good marketing. The KLYPIX desktop app renders the same brain.klypix as a living spatial map, with health, freshness, provenance and orrery lenses, an unresolved-questions triage view, and a one-click flow that connects a folder's brain to six coding agents. You can read, correct, archive and re-link what your agents recorded.

The file is co-owned. When the app saves a brain it re-reads the disk copy inside the same capture lock the agent hooks use and union-merges instead of overwriting, so a card an agent captured while you had the file open is kept. The merge verifies its own output and aborts rather than emit a file missing a card. Deletes require an explicit tombstone, so a card that is merely absent is never inferred as deleted.

The app is a separate, proprietary Windows product. The format, this server and the hooks are Apache-2.0 and work with no app installed. The app's interface is available in English and Arabic (some newer panels are still English-only).

KLYPIX canvases and your AI tool

Beyond project brains, the same connection reads and writes the KLYPIX canvases (spaces) saved on your PC. Your AI tool reads what KLYPIX has already read, and the files a saved canvas holds:

• read_canvas prints every card with its id; read_card_contents returns what is inside a card. From what KLYPIX saved: the transcript on a video card, the text card Read contents made for a reel or web page, an OCR card for a photo, a folder's file list. From the files embedded in the saved canvas, with KLYPIX closed: a text file's words, a photo (a smaller copy when it is large), and PDFs, Office and other files as a local path with the previews KLYPIX saved — see Reading what is inside cards below. Audio and video come back as a path only; what they say comes from a reading KLYPIX saved. For a reel, a web page or a video, choose Read contents in KLYPIX first (select the card, press Enter), let the canvas save, then ask your AI tool — or, with KLYPIX open on Windows, let your AI tool ask KLYPIX to read it (App mode below).
• What a person set up in KLYPIX is respected: cards inside a box locked from AI tools are left out of every read; frozen cards are marked read-only; collapsed boxes, comments and tags are shown.
• klypix_status tells your AI tool what KLYPIX can do on this PC right now, and which step the person has to take.
• A canvas that is open in KLYPIX is not written. KLYPIX builds that write the open-canvas lease (%APPDATA%\klypix\agent-bridge\endpoint.json, no secret in it) make add_to_canvas refuse that canvas and say why; project brains are the exception, because KLYPIX merges them. With an older KLYPIX, add_to_canvas writes and its reply tells the person to close the canvas's tab and open it again.
• Text that comes back from cards, pages, reels and files is fenced as data, never instructions.

App mode: your AI tool uses KLYPIX while it is open

On Windows, while the KLYPIX app is open and Settings → Project → AI tools on this PC is on (it is on by defa