Kawa Code

Kawa Code MCP

Team-aware memory for AI coding assistants. Track intent, record decisions, and see when a teammate is editing the same code — in real time, before commit.

@kawacode/mcp is the official Model Context Protocol (MCP) server for Kawa Code. It lets Claude Code, Cursor, and any MCP-compatible AI assistant:

• Remember what you're working on across sessions, branches, and machines — no more re-explaining the architecture every morning.
• Surface team conflicts before they happen — know when a teammate is editing the same file or function in their working copy *right now*, before either of you commits.
• Capture architectural decisions with their reasoning — future you (and future AI sessions) inherit the team's accumulated context instead of relitigating choices.
• Link commits to intent automatically — every commit gets the *why* attached, not just the diff.

Prerequisites

Required

• Node.js >= 18.0.0 — runtime for the MCP server
• [Kawa Code](https://kawacode.ai) desktop app running — kawa.mcp is a thin MCP-to-IPC adapter; all git operations, storage, and API communication happen in Kawa Code

Optional (for history inference)

• Anthropic API key — your own Claude API key, passed as a parameter to the inference tools
• [GitHub CLI (`gh`)](https://cli.github.com/) — enables richer data tiers (PR descriptions, review comments, issue discussions). Without gh, tiers 2 and 4 are skipped automatically

Installation

Add the MCP in your AI configuration, for example on Claude Code:

claude mcp add -s user kawa-intents -- npx -y @kawacode/mcp

For Cursor AI, install the MCP with npm install -g @kawacode/mcp and add it to ~/.cursor/mcp.json.

{

"mcpServers": { "kawa-intents": { "command": "kawacode-mcp" } } }

Note that the MCP will not be automatically updated to future versions in this scenario. To upgrade to a newer release, run npm update -g @kawacode/mcp.

Manual Installation

For the project you want Kawa Code to run on, create a .mcp.json file in your project root (recommended for teams — commit it to git):

{

"mcpServers": { "kawa-intents": { "type": "stdio", "command": "npx", "args": ["-y", "@kawacode/mcp"] } } }

Usage

The MCP server works together with the Kawa Code application, Kawa Code IDE extensions, and AI code generators such as Cursor AI and Claude Code.

Pre-edit decision check (Claude Code hook) — retired

Retired 2026-08-14. Do not wire this up. Kawa Code no longer installs it, and the setup wizard no longer asks for it.

This hook fired before every Edit/Write and surfaced prior reasoning attached to the file being changed. It was retired because its retrieval could not reach the decisions that mattered: it read only the most recently updated 100 decisions per repository, and architectural constraints — precisely what it existed to surface — are written once and then age out of a recency window permanently. On one of our own repositories, 160 decisions were of the surfaced types and only 17 were still inside that window.

If you already installed it, nothing breaks. The kawacode-on-pre-edit binary still ships, and an existing entry in your settings.json keeps working. Kawa Code will not remove it for you — delete it yourself if you want it off:

"PreToolUse": [ { "matcher": "Edit|Write", "hooks": [ … ] } ]

Nothing is lost on team coordination. The live collision signal moved to the Stop hook some time ago, and that is now the only edit-level coordination surface. It reports teammates whose *in-progress, uncommitted* edits overlap the lines you touched this turn — conflict detection before a merge conflict can exist. See Team conflict detection.

Key Features

• Real-time team conflict detection — see when a teammate is editing the same files or lines in their working copy, *before either of you commits*. Most version-control tooling shows you this after the merge conflict; Kawa shows you before. Kawa can also *judge* an overlap and apply the safe tier of merge for you — though that write only happens in an agent-owned worktree.
• Cross-session AI memory — your AI assistant picks up where it left off across days, branches, and machines. No re-explaining the architecture every morning.
• Decision history with reasoning — record forks, trade-offs, and abandoned approaches with their *why*. Future sessions and teammates inherit the context instead of re-deriving it.
• Commit ↔ intent linkage — every commit is automatically associated with the intent that drove it. git log shows what changed; Kawa shows why.
• Smart context retrieval — relevance-based loading; only what the current task needs.
• Zero-knowledge encryption — code blocks encrypted client-side before sync. The Kawa cloud cannot decrypt your team's code.
• Cross-platform — works with Claude Code, Cursor, and any MCP-compatible AI assistant.

Running several agents in parallel

Kawa Code is built for more than one worker on a repository at a time — that's what the conflict detection is *for*. If those workers are AI agents you're running yourself, give each one its own git worktree. Agents sharing a single checkout overwrite each other's edits with no conflict marker and no git history: nothing is committed between the two writes, so nothing notices.

Set up worktrees

In Claude Code, background sessions already require a worktree — worktree.bgIsolation defaults to "worktree", which blocks edits to the main checkout until the session enters one. You only need to touch it if a project has explicitly opted out with "none". Subagents take isolation: "worktree" per spawn.

Two settings are worth tuning, because the defaults surprise people:

{

"worktree": { "baseRef": "head", "symlinkDirectories": ["node_modules", "target"] } }

• `baseRef` — defaults to "fresh", which branches from origin/ . If you work on unpushed commits, set "head" to branch from your local HEAD instead. Either way this is a *commit* boundary: uncommitted working-tree changes don't travel into a new worktree, so land your work before spawning agents that need it.
• `symlinkDirectories` — nothing is symlinked unless you say so, so every worktree gets its own copy of whatever you leave out. Symlink *dependency* directories freely: node_modules is the same content for every worktree, and sharing it costs nothing. Do not symlink compiled-language build output — target/, build/, obj/. Those tools name artifacts deterministically from the crate/module and its inputs, *without* encoding which checkout they came from, so two worktrees building into one directory write the same filenames and silently overwrite each other. The symptom is the dangerous part: your suite goes green while running another checkout's binaries. Only a test that resolves a path baked in at compile time (Rust's env!("CARGO_MANIFEST_DIR"), include_str!, or an equivalent) will notice; everything else passes. If a suite ever looks suspiciously green after another checkout built in the same place, clean the build directory and re-run before believing it.

Because compiled build directories can't be shared, they multiply — one per worktree, each growing independently, and they get large enough to matter (a mature Rust target/ reaches hundreds of gigabytes). Two things keep that affordable, and they solve different halves:

• Speed — a compiler cache such as sccache is safe across worktrees precisely because it caches *results* keyed by input hash rather than sharing an output directory.
• Disk — prune periodically. For Rust, cargo-sweep removes stale artifacts by age or to a size cap; wire it into whatever cadence fits your setup — after merging a worktree back is a natural trigger. One caveat worth knowing before you rely on it: sweeping only reclaims artifacts the build tool still tracks. If that index has been lost, the leftovers are orphaned and a sweep reports nothing to do no matter the flags — a full clean is the only thing that reclaims them.

Keeping agents from colliding

Isolation alone would just give you several agents doing overlapping work in private. Kawa's job is the coordination on top.

Each agent session gets its own identity, and intents are tracked per session — so several intents can be active on one repository at once, each with its own current focus, without a lock and without agents clobbering each other's context. From there the normal machinery applies across agents exactly as it does across teammates: get_relevant_context surfaces what the *other* agents have already decided, create_and_activate_intent hands the user a decision in Kawa Code when new work overlaps something already in flight, and the Stop hook reports, once per turn, where another agent's live edits intersect yours.

The practical result: your agents inherit each other's decisions instead of re-deriving them, and you find out about overlapping work while it's still cheap to redirect — not at merge time.

Auto-resolution requires a worktree

Kawa can do more than *report* an overlap — arbiter_resolve judges each one, and arbiter_apply will write the safe tier of merge for you. That write is deliberately gated:

arbiter_apply writes only in an agent-owned worktree. On a human checkout — or when a peer holds the file-set lock — it stays suggest-only.

This is the sharpest practical reason to put agents in worktrees. Run them on a shared checkout and auto-resolution silently never engages; you get the conflict surfaced and nothing else, with no error to tell you a capability was switched off. The guardrail is intentional — Kawa won't rewrite a human's working tree underneath them — but it does mean the setup decides whether half the feature is available.

When an overlap is waiting on you

When an agent asks to start work that overlaps an intent already in flight, the agent doesn't get to decide. Kawa Code parks the request and asks you, in the Orchestration panel: create_and_activate_intent returns pending_approval with a pendingId, and the agent re-checks that id as it goes.

A parked overlap is not a stop. Nothing in Kawa Code halts an agent mid-task, and nothing is meant to — a refusal that froze the session would strand it for as long as you were away, and by the time you read the card the edits are usually already on disk. So the agent tells you the card is waiting and carries on with whatever doesn't depend on the intent existing. Cancelling behaves the same way: it withholds the intent and *asks* the agent to stop, so the card reports how many turns that session has taken since you cancelled rather than pretending the work was undone.

Can't see the card?

Check the panel's scope first — this is the usual cause, not expiry. Orchestration reads across repositories by default, but scoped to the current project it lists only cards for the repository you have focused, and the agent that parked the request is often working in a different one. Widen the scope, or focus that repository.

Lapsing after 24 hours — the card waits, the agent doesn't

A parked request has a 24-hour window, but the window bounds how long the agent waits, not how long you have:

**Expiry marks a request stale; it does not