Kawa Code MCP
Kawa Code MCP is a team-aware memory and coordination server for AI coding assistants: it tracks intents, records decisions, recalls task context, and surfaces live overlap with teammates/agents.
Recall relevant past intents and decisions via
get_relevant_context, then expand a decision’s full rationale withget_decision_detail.Manage per-session intents: check active intent, create/activate/update/complete intents, list team intents, and inspect intents for a repo, file, or line range.
Detect overlapping or conflicting work via
detect_intent_conflictsand file/line intent queries.Record and curate decisions (fork, abandoned, discovery, constraint, tradeoff, dependency), including session edits/deletes before sync.
Check files/line ranges for prior reasoning before editing and acknowledge temporary overrides; README notes the automatic pre-edit hook is retired.
View uncommitted changes tied to the active intent.
Handle live peer code collisions: fetch peer snippets, get AI arbitration verdicts (
arbiter_resolve), and auto-apply only safe-tier merges in agent-owned worktrees (arbiter_apply).Bootstrap or extend repo knowledge from git history with
infer_history(cost estimate first, optional PR/issue context, async/resumable); schema also exposesevolve_decisionsandupdate_features, though README says decision evolution is automatic andupdate_featureswas removed.Work with Claude Code, Cursor, and other MCP clients through Kawa Code desktop IPC, with zero-knowledge encryption and team sync handled by the app/cloud.
Integrates with GitHub CLI to fetch pull request descriptions, review comments, and issue discussions for richer data tiers in context retrieval.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Kawa Code MCP what are my teammates currently editing?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 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) — enables richer data tiers (PR descriptions, review comments, issue discussions). Withoutgh, tiers 2 and 4 are skipped automatically
Related MCP server: memfed
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 logshows 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 fromorigin/<default-branch>. 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_modulesis 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'senv!("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
sccacheis safe across worktrees precisely because it caches results keyed by input hash rather than sharing an output directory.Disk — prune periodically. For Rust,
cargo-sweepremoves 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_applywrites 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:
when | the agent | your card |
within 24h | re-checks the | in the panel, marked needs your decision |
after 24h | told the request lapsed, and to ask again | still in the panel, marked Lapsed — and still answerable |
Expiry marks a request stale; it does not retire it. The clock running out records that you were away, not that you refused — so the card keeps its actions, and approving a lapsed request creates the intent exactly as it would have the day before. Only your answer closes a request. A lapsed card stays until you answer it; what ages out is an answered one, which only has to survive long enough for the agent's next check.
If your agent asked again
The agent is told to re-request when its request lapses, which parks a fresh card. That card carries over the decisions the session recorded in the meantime and retires the lapsed one, so you get one card for the work rather than two. The overlaps themselves are detected afresh, so the list reflects the repository as it stands now rather than as it stood a day ago. You can also prompt it yourself:
The intent request lapsed — request it again.
Either way your committed code is untouched: the request and the card are coordination state, not your work.
Decisions recorded while you were deciding
Your agent doesn't stop, so it usually records reasoning before you ever see the card. Those decisions are saved the moment they're made — they never wait on you — and the card lists them, so you can judge the overlap against what the session actually concluded rather than against its opening title.
When you approve, they're attached to the intent that gets created, including the ones recorded after the request lapsed. If you cancel, they stay at the repository level with no intent: you ruled, no intent will exist, and the reasoning is still searchable and still surfaced by get_relevant_context. Nothing is discarded either way.
The one case that loses attribution is a different agent session re-asking for the same work — the worklist follows the session that recorded it. So the habit worth keeping is simply: answer the card while that session is still around.
Handing off work to a teammate (no session export)
Because the reasoning behind your work — your intents and recorded decisions — lives in Kawa Code rather than in the chat log, a teammate can pick up where you left off from a single prompt. No transcript sharing, no session restore.
Commit or push your code first. A handoff prompt carries your reasoning, not your uncommitted working tree — so land the code (or publish the pre-commit diff) before you hand off, otherwise your teammate inherits the decisions without the diff that goes with them.
Grab the intent id. The id of the intent you were working under — your agent can read it back with
check_active_intent, or you can find it in the Kawa Code app.Hand over a one-line prompt, e.g.
Follow up on intent <intent-id>: <what's left to do>.Your teammate pastes it into a fresh session. Their agent calls
resume_intent(<id>)— one call that adopts the intent as their current focus and loads its recorded decisions — resuming the thread with full context, even though it never saw your chat.
What transfers: the intent, its decisions, and (once committed) its code. What doesn't: your chat transcript and any session-local state. Your session's current focus and its per-turn bookkeeping are yours — your teammate's session starts its own and re-reads the shared record, rather than inheriting judgments you made in the moment. That is what you want: the reasoning carries over, the in-session state does not.
Teams: to make the handoff seamless, add one line to your shared CLAUDE.md so the agent always treats a follow-up prompt as resuming the named intent instead of opening a new one:
When a prompt says "follow up on intent
<id>" (or similar), callresume_intent(<id>)to adopt that intent and load its decisions — do not create a new intent for it.
Migrating or rewriting a codebase? Transplant its decisions
When you port a codebase to a new language or rebuild it in a fresh repository, the code moves — but the reasoning usually doesn't. The source repo's decision history knows why retired approaches were retired, which constraints are load-bearing, and where the security landmines are. With Kawa Code, that history becomes a first-class migration input.
Decisions are scoped per repository, so the new repo won't surface the old repo's history automatically. Transplant them slice by slice as you port — this is the recall-transplant workflow:
Recall before porting each slice. Call
get_relevant_contextagainst the source repo with a description of the subsystem you're about to port (name its key files). This surfaces the forks, constraints, trade-offs, and discoveries that shaped it.Expand what matters. Recall returns summaries — call
get_decision_detailon the load-bearing hits for the full rationale and consequences.Classify: stack-portable vs stack-bound. Domain truths port: protocol contracts, cost/scale rationale, security discoveries, "we tried X and retired it" warnings. Mechanics of the old stack don't: build-tooling quirks, runtime workarounds, library-specific fixes. Only the portable ones move.
Re-record the portable ones in the target repo with
record_decision, citing provenance in the summary or rationale (e.g.[transplanted from <source-repo> <decision-id>]). Merge decisions that form one lineage into a single record.Let the transplants shape the port and its tests. A transplanted durability rationale should become a test that proves the property survived the rewrite; a retired-approach warning should stop the new stack from reintroducing it.
The payoff compounds: the port doesn't re-litigate settled arguments or faithfully reproduce old bugs, negative knowledge survives even though the code that motivated it was deleted long ago, and at cutover the new repo starts with a curated decision corpus instead of an empty one.
The CLAUDE.md template ships a compact version of this workflow, so agents set up through the Kawa Code welcome flow follow it automatically.
Occasional operations
Most Kawa tools run every turn — check the active intent, recall context, record a decision. The operations below are different: you run them rarely, sometimes once per repository. They cost real time and money, and they are not part of the per-turn loop.
Seeding a repo from its git history — infer_history
A brand-new Kawa repo knows nothing about work that predates it. infer_history mines the existing commit history into intents and decisions, so recall has something to draw on from day one. Run it once when you connect a repo with meaningful history; after that it extends incrementally.
It is agent-invoked — ask your assistant, e.g. "Run infer_history with max 3000 commits". There is no button for it in the Kawa Code app.
Always estimate first. The tool defaults to estimateOnly: true, which returns a token/cost preview without running anything. Look at the number, then re-run with estimateOnly: false to actually start. A run is asynchronous — it returns immediately and reports progress in the Kawa Code app — and resumes from where it stopped if interrupted.
Parameter | Default | Purpose |
|
| Preview cost without running. Set |
| resume | How many recent commits to analyze. Omit to continue from the last run. |
| — | Git revspec ( |
|
| Pull in PR/MR descriptions and issue discussions. Needs an authenticated |
|
| Enable when one commit often mixes unrelated changes. |
| — | Per-run cap on stories analyzed. |
| — | Affects the estimate only. The run's model is configured in the Kawa Code app. |
|
| Override the re-run guard — see below. |
The re-run guard. If the repo already has intents and the run can't cleanly resume (missing or unreachable cursor), or HEAD isn't on the default branch, the call stops and returns needsDecision instead of running. That's deliberate: re-running blind duplicates intents. Read the reason, and only pass force: true if it genuinely applies. Prefer running on main/master; force exists for the deliberate feature-branch case.
GitHub and GitLab are both supported; the forge is detected from the remote origin.
Decision evolution — automatic, no call needed
Curating decisions into an evolution graph is phase 5 of infer_history, run automatically once the analysis completes. There is no separate step and nothing to invoke.
Earlier versions exposed an
evolve_decisionstool. It has been removed: it required astoriesarray that only ever existed inside the pipeline's own memory, so no assistant could construct a valid call. Nothing is lost — the curation still runs, as part ofinfer_history.
Updating the feature catalog — use the Features panel
Features group a repo's intents into a browsable catalog. Rebuild it from the Features panel in the Kawa Code app:
Update features — additive. Folds intents that aren't in the catalog yet into the existing features. This is the everyday action.
Rebuild — cold rebuild from scratch, keeping locked features. Use when the catalog has drifted badly.
Progress shows in the app, and the catalog also extends automatically after an infer_history run.
Earlier versions exposed an
update_featuresMCP tool that sent the same request as the Update features button. It has been removed — one button and one tool doing the identical thing meant every session paid for a tool schema it never needed. Press the button instead.
Development
# Watch mode (auto-rebuild on file changes)
npm run dev
# Build TypeScript to JavaScript
npm run build
# Clean build artifacts
npm run clean
# Run the MCP server directly
npm startTesting the MCP Server
To test the MCP server without integrating it into an AI assistant:
Build the project:
npm run buildRun the server:
npm startThe server communicates via stdio (standard input/output)
You can send MCP protocol messages via stdin to test tool functionality
Development Tips
Use
npm run devto auto-rebuild during developmentCheck stderr for server logs (stdout is reserved for MCP protocol)
Ensure Kawa Code is running before testing
Architecture
Claude Code / Cursor AI
↓ MCP Protocol (stdio)
kawa.mcp (this server)
↓ Huginn IPC (Unix socket / Named pipe)
Kawa Code Desktop App
└─ HTTP Client
↓ REST + SSE
Kawa API (cloud)
└─ Team sync & zero-knowledge encryptionContributing
Contributions are welcome. Please read CONTRIBUTING.md and CLA.md.
License
This project is source-available under the Kawa Code Source Available License.
You may run and modify the software for personal or internal use.
See LICENSE for details.
Available Tools
25 toolsactivate_intentA
Activate an existing intent by ID — sets it as THIS session's current focus.
Use this to:
Switch your current focus to a different intent found via list_team_intents or get_relevant_context
Re-activate an intent that was deactivated (e.g., to complete it)
Resume work on a previously created intent
Resume an "abandoned" intent (see below)
Accepts both cloud IDs (from get_relevant_context / API) and local UUIDs (from list_team_intents).
Multi-active model: activating an intent only moves YOUR session's current pointer. Many intents can be active on a repo at once (one current per session/teammate), so this never blocks on or displaces another session's active intent — there is no lock to take over.
Resuming abandoned intents:
Abandoned intents have their decisions soft-deleted (invisible to recall and get_relevant_context). Activating one transparently restores them — single-intent decisions for this intent get their soft-delete cleared so the prior reasoning becomes visible again. Multi-intent decisions stay visible throughout (they were never soft-deleted).
Inputs: intentId (required), repoPath (required), forkAuthor, repoOrigin, +1 more.
arbiter_applyA
Resolve live code overlaps and AUTO-APPLY the safe tier. Kawa judges → adversarially verifies → and, for the trivial tier only (high-confidence single-range merge that passes verify), writes the merge to your worktree, records a decision, and republishes. Writes happen ONLY in an agent-owned worktree (a linked git worktree); on a human checkout — or when a peer holds the file-set lock — it behaves like arbiter_resolve (suggest-only, no writes). Returns per-overlap outcomes { tier, applied, announcement, verifyIssue?, verdict }. Call it when you are ready to incorporate the result, then RE-READ any file it applied to (it changed on disk). For surfaced (not-applied) overlaps, use get_resolution_context to see the peer code and resolve manually.
Inputs: overlaps (required), repoPath (required), intentId, forkAuthor, +2 more.
arbiter_resolveA
Get Kawa Code's AI verdict for live code overlaps with peers — SUGGEST-ONLY, never writes. For each overlap ({peerUid, filePath, ranges} from the Stop collision report), Kawa decrypts the peer's version locally (zero-knowledge) and judges it compatible / auto_resolvable / conflict, with confidence, a perf/security risk read, and a tier (0 no-op · 1 trivially auto-appliable · 2 draft-and-confirm · 3 conflict). Use it to understand a forming conflict before acting. For a surfaced tier-2/3 overlap, call get_resolution_context to read the peer's actual code. To actually apply the safe tier, use arbiter_apply.
Inputs: overlaps (required), repoPath (required), intentId, forkAuthor, +2 more.
check_active_intentA
REQUIRED: Call this tool BEFORE writing any code.
Returns THIS session's current intent (intent / hasActiveIntent) if one is
set. If not, ask the user to confirm intent details and then call
create_and_activate_intent.
Multi-active model: the active intent is PER SESSION. Many intents can be active
on a repo at once — your current is independent of other sessions'/teammates'.
The response also includes activeIntents: the repo's full active set (every
session's current intent, with id/title/status/createdBy/author) for awareness
and orchestration. hasActiveIntent reflects only YOUR session; activeIntents
may be non-empty even when you have no current.
An active intent tracks what the user is working on, enabling:
Better code context for AI-generated changes
Conflict detection with team members
Automatic assignment of code blocks to the intent
Status semantics:
"active" — normal, in-progress. A stale intent simply stays "active"; the sweeper preserves its work without any status transition.
terminal states — committed / pushed / done / abandoned / superseded.
Inputs: repoPath (required), forkAuthor, repoOrigin, workspaceId.
complete_intentA
Mark the active intent as completed and clear it.
Call this after a successful git commit to:
Update the intent status (committed/pushed/done/abandoned)
Store the commit SHA for tracking
Clear the active intent so a new one can be started
Status values:
"committed": Code is committed locally (default)
"pushed": Code has been pushed to remote
"done": Work is fully complete
"abandoned": Work was discarded without committing
REQUIRED: Inspect the response after calling this tool. Three outcomes:
response.success === true: The task is complete. Briefly acknowledge the commit and — if response.committedDecisionCount > 0 — mention that N distilled architectural decisions were recorded for the intent. Do NOT enumerate the decisions inline; they're visible via the orchestration panel and via get_intent_decisions / get_relevant_context if the user wants details. If response.apiSyncDeferred === true, also mention that the API sync was deferred; the queued writes will replay on the next sync tick. If response.collisions is non-empty, a live collaborator's (HAI's) in-progress edits overlap the work you just completed — surface it as a coordination heads-up (who, and which files), naming response.collisions[].label and the files. It's advisory, not a failure; the completion still succeeded. If response.deferredConflicts is non-empty, the distillation produced N decisions that conflict with existing standards — the completion STILL SUCCEEDED (the commit landed: status flipped, code blocks captured). Those decisions are deferred: parked for a disposition in the Orchestration panel, where the user picks per decision: supersede the standard, keep both (records a "contradicts" edge for a deliberate divergence / false positive), or reject the distilled decision. Tell the user "N decision(s) need a disposition in the panel." There is NOTHING to retry — do NOT re-run complete_intent.
response.success === false AND response.reason === "transient-failure": The distiller LLM call or the conflict-check API call errored. The ephemerals are preserved (the bucket is intact), and the intent stays "active". Tell the user the failure stage (response.failedStage) and the underlying error, then suggest retrying once the issue clears, or abandoning if the failure persists.
In a non-interactive (autonomous) session: if response.deferredConflicts is non-empty, log it at INFO and continue — the commit already landed and the decisions await disposition in the panel. There is no blocking state.
Inputs: repoPath (required), status, intentId, commitSha, +5 more.
create_and_activate_intentA
Create a new intent from the user's request and mark it as active for THIS session.
Call this when check_active_intent returns no active intent for your session. Before calling:
Summarize what the user is asking for
Ask the user to confirm the intent details (title, description, type)
Then call this tool with the confirmed details
This ensures all AI-generated code gets properly tracked and attributed.
Multi-active model: many intents can be active on a repo at once (one per session/teammate). Creating + activating one only sets YOUR session's current focus — it never blocks or displaces another session's active intent, so there is no lock conflict to resolve.
If the tool returns conflicts (action="conflict"), it found an existing team-member intent that overlaps semantically or in files. Present the conflict details to the user and ask whether to proceed. If yes, retry with force=true to bypass conflict detection.
Inputs: title (required), repoPath (required), description (required), force, +5 more.
detect_intent_conflictsA
Find intents from other team members that potentially conflict with the active intent.
When to use:
Before committing, to surface overlapping team work so the user can coordinate before merging.
Inputs of note:
intentId: the active intent to check against.minScore(optional): minimum match score to include in results.
Returns scored conflict candidates with:
score: how strongly the candidate matches (higher = more likely conflict).overlappingFiles: files affected by both intents.decisions: decisions attached to the conflicting intent.author: who is working on the conflicting intent.
The list is informational — review candidates and their decisions to decide whether coordination is needed.
Inputs: intentId (required), repoPath (required), minScore, forkAuthor, +2 more.
edit_session_decisionA
Edit or delete a decision in the current session.
Use this when reviewing decisions before commit:
action: "update" - Modify the decision fields
action: "delete" - Remove the decision entirely
Only ephemeral (in-flight) session decisions are editable. Once a decision is
synced to Kawa Code, it is immutable — refine it instead by recording a new
decision with supersedes: [<id>].
This allows users to curate their decision history before it's persisted.
Inputs: action (required), intentId (required), repoPath (required), decisionId (required), +4 more.
evolve_decisionsA
Curate a set of previously extracted stories so that only the decisions still worth keeping are persisted.
When to use:
After running
infer_historyin story-only mode (rare —infer_historyalready chains this step automatically).When you have a pre-existing set of stories you want to re-curate without re-running history extraction.
Inputs:
stories: array of story objects from a previousinfer_historyrun.repoPath(optional): when provided, curated results are persisted as intents and decisions for the repo after curation finishes.model(optional): Anthropic model used for the curation pass.
Behavior:
Runs asynchronously — returns immediately with a started/pending status while progress is reported separately.
Inputs: stories (required), model, repoPath, forkAuthor, +2 more.
get_decision_detailA
Expand one decision to its full detail.
Recall surfaces (get_relevant_context, get_project_decisions, get_session_decisions) return decisions summary-only to keep context lean. Use this to pull the full reasoning for a single decision you want to open — pay for detail only where you ask for it.
Inputs:
decisionId: the decision to expand (theid/decisionIdfrom a recall result).
Returns the decision's rationale, context, consequences, alternatives, symptom, appliesWhen, surface, and related metadata. found: false when the id is unknown in this repo.
Inputs: repoPath (required), decisionId (required), forkAuthor, repoOrigin, +1 more.
get_intent_changesA
Get uncommitted changes in the repository along with the active intent info.
Use this tool before prompting the user about committing to show:
The active intent title and description
Number of modified, added, and untracked files
Any warnings (e.g., pre-existing changes from before intent activation)
This helps you construct an informative commit prompt like: "You have uncommitted work on '[intent title]' (N files changed)..."
Inputs: repoPath (required), forkAuthor, repoOrigin, workspaceId.
get_intents_for_fileA
Get all intents that have code blocks in this file.
Use this before modifying a file to:
See what work is already in progress
Identify potential conflicts with team members
Understand the context of existing code changes
Returns intent details including author, status, and specific line ranges.
Inputs: filePath (required), repoPath (required), forkAuthor, repoOrigin, +1 more.
get_intents_for_linesA
Get intents covering a specific line range.
Use this before modifying specific lines to check for conflicts:
Warns if the lines overlap with another team member's active intent
Shows the exact overlap range
Helps avoid merge conflicts and duplicate work
Returns overlap details so you can work around or coordinate with team members.
Inputs: endLine (required), filePath (required), repoPath (required), startLine (required), +3 more.
get_project_decisionsA
Get all decisions recorded for a project across all intents.
Use this to review the project's decision history:
See what architectural decisions have been made
Understand past trade-offs and their rationale
Find decisions affecting specific files
Review constraint violations that were avoided
Returns:
decisions: Array of decisions with their intent context
count: Total number of decisions
Each decision includes (summary-only, to keep context lean — call get_decision_detail(decisionId) for full rationale/context/consequences/alternatives):
intentIds: The intents this decision belongs to (array — a decision can span multiple intents)
type: fork, abandoned, discovery, constraint, tradeoff, or dependency
summary: Brief description of the decision
relatedFiles: Files affected by this decision
constraintViolations: Options that were rejected due to constraints
Inputs: repoPath (required), forkAuthor, repoOrigin, workspaceId.
get_relevant_contextA
Find past intents and decisions relevant to the current user request.
When to use:
After you have done a quick initial exploration of the user's request and know which files are involved. Calling earlier with only a vague prompt gives weak results.
To pull task-specific context instead of dumping all recent activity — preferred for large projects.
Inputs of note:
prompt: the user request, in their words or your paraphrase.activeFiles(recommended): files you have identified as relevant to the request. Significantly improves relevance.maxIntents,maxDecisions,minRelevance: result-shaping caps and threshold.
Returns:
relevantIntents: past work units (intents) related to the task, scored by relevance.relevantDecisions: prior decisions related to the task — both intent-scoped and repo-scoped. Summary-only (no inline rationale, to keep context lean); callget_decision_detail(decisionId)for the full rationale/context/consequences of any decision you want to open.
Recommended sequence:
check_active_intentat session start to resume any existing work.Briefly explore the user's request to identify involved files.
get_relevant_contextwith the prompt andactiveFilesto inform the approach.
Inputs: prompt (required), repoPath (required), forkAuthor, maxIntents, +5 more.
get_resolution_contextA
Resolve a live code collision with a peer BEFORE you write (Layer C resolution handoff).
Call this when the Stop hook's collision report (or complete_intent's resolution_required gate) surfaced a live peer (a teammate or AI agent editing the same lines). Pass that collision's uid as peerUid and its overlapping ranges. You get back:
peerSnippet — the peer's actual (decrypted) code at the overlapping lines, so you can see what they wrote.
decisions — recorded reasoning attached to this file (region context).
guardrail — the policy you must follow when resolving: • Never overwrite a peer's COMMITTED work — yield or merge. Only override an uncommitted live diff, and only with a recorded rationale. • Your resolution is an ordinary git edit (revert/diff is the undo) — stay in your own working tree; build no bespoke undo. • Before completing, record_decision(type=fork|tradeoff, …) explaining how you resolved (and supersedes the peer's decision if you overrode it). • Choose or synthesize ONE coherent result — never blindly interleave both diffs.
This is advisory and proactive (no lock). Use it to adapt your edit and avoid the conflict.
Inputs: ranges (required), peerUid (required), filePath (required), repoPath (required), +4 more.
get_session_decisionsA
Get all decisions recorded in the current session for an intent.
Use this before committing to review what decisions were captured during development. Decisions are presented for user review and can be edited or removed before being persisted.
Returns:
intentId: The intent these decisions belong to
decisions: Array of decision points (summary-only — call get_decision_detail(decisionId) for full rationale/context/consequences/alternatives)
count: Number of decisions recorded
Inputs: intentId (required), repoPath (required), forkAuthor, repoOrigin, +1 more.
infer_historyA
Analyze a repository's git commit history and produce structured development knowledge (intents and decisions) for the repo.
When to use:
To bootstrap a repository that has no recorded intents/decisions yet.
To extend coverage for new commits since the last run (resumes automatically when no
commitsvalue is provided).
Inputs of note:
estimateOnly(default true): returns a token/cost estimate without running. Call withestimateOnly: truefirst to preview cost, then re-call withestimateOnly: falseto run.commits(optional): how many recent commits to analyze. Omit to resume from where the last run stopped (or fall back to a sensible default on first run).commitRange(optional): git revspec selecting a specific window —"sha1..sha2","branch1..branch2","sha1^!"for a single commit. Mutually exclusive withcommits. Useful for recovering from dropped batches or backfilling specific PRs / branches without re-running the full history.contextIssues: include PR/MR descriptions and issue discussions when an authenticated forge CLI (ghorglab) is available; auto-skipped otherwise.allowCommitSplitting: enable when commit history is messy and a single commit may cover unrelated changes.model,maxStories: Anthropic model and per-run cap.force(default false): override the re-run guard (see Behavior).
Behavior:
A run is asynchronous — returns immediately with a started/pending status; progress is reported separately.
Results are persisted as intents and decisions for the repo on completion.
If interrupted, re-running resumes from where it left off.
Re-run guard: a clean incremental resume runs automatically. But if the repo already has intents and the run cannot cleanly resume (missing/unreachable cursor), or HEAD is not on the default branch, the call STOPS and returns
needsDecisioninstead of running — re-running blind there risks duplicate intents. Present the reason to the user and, if they confirm, re-call withforce: true. Run on the default branch (main/master) whenever possible; inferring a feature branch is whatforceis for.GitHub and GitLab are supported; the forge is detected from the remote origin.
Inputs: repoPath (required), force, model, commits, +5 more.
list_team_intentsA
List intents from team members for this repository.
Use this to:
See what your team is working on
Check for potential overlapping work before starting a new task
Review the status of various features/refactors in progress
Filtering (status, author, date range) and pagination are applied server-side across the full result set (default: 50 per page; use limit/offset to page). count is the total number of matching intents, not just the returned page.
Inputs: repoPath (required), limit, since, until, +6 more.
log_workB
DEPRECATED — trivial changes (typos, one-line fixes, obvious bugs, doc updates, config changes) should skip the intent workflow entirely: just make the change and commit, no intent needed. Do not call this tool. Kept available for backwards compatibility only and will be removed in a future release.
Inputs: title (required), repoPath (required), files, forkAuthor, +2 more.
pre_edit_acknowledgeA
Mark decisions as consciously overridden for the rest of this session.
Phase 3's PreToolUse hook calls this when the agent passes force: true on an Edit tool call to bypass a pre_edit_decision_check block. Adds the surfaced decision IDs to an in-memory session cache; subsequent pre_edit_decision_check fires filter those IDs out so the same block doesn't re-fire.
The cache resets when the MCP server process exits (= the agent session ends). For persistent override across sessions, record a fork decision via record_decision(type: "fork", supersedes: [<id>]) instead.
Returns:
acknowledged: number of newly-added IDs (existing IDs are deduped silently)
cacheSize: total IDs currently in the session override cache
Inputs: decisionIds (required), repoPath, forkAuthor, repoOrigin, +2 more.
pre_edit_decision_checkA
Check whether the line range about to be edited has prior recorded reasoning attached.
Call this BEFORE editing code in a kawa-indexed repo. Surfaces:
Tier 1a — overlapping intents whose blocks cover these lines (line-precise team coordination + intent-scoped decisions)
Tier 1b — repo decisions whose relatedFiles include this file (file-coarse, catches infer_history-extracted constraints)
(Live-collaborator code-collision awareness is no longer reported here — it now arrives once per turn at the Stop hook. This tool is purely the semantic, decision-based check.)
Decisions already overridden via record_decision(supersedes=...) are filtered out automatically.
Recommendation maps to action:
"proceed" — nothing relevant; safe to edit
"review" — surfaced context worth inspecting before editing
"investigate-upstream" — prior constraint or abandoned approach matches; don't proceed without reading the rationale and either revising the change or recording a new fork decision that supersedes the old one
Also returns the smallest enclosing function/method symbol via tree-sitter (Rust/TS/JS/Python only; null for other languages) for warning readability.
Inputs: endLine (required), filePath (required), repoPath (required), startLine (required), +5 more.
record_decisionA
Silently record a decision point during development.
Call this tool when you:
Choose between multiple alternatives (type: fork)
Try an approach that fails or is rejected (type: abandoned)
Find unexpected behavior or limitations (type: discovery)
Identify a hard constraint that must be respected (type: constraint)
Make an explicit trade-off between competing concerns (type: tradeoff)
Select an external library or dependency (type: dependency)
Decisions can be intent-scoped (tied to a specific work unit) or repo-scoped (general knowledge like discoveries and constraints). Omit intentId for repo-scoped decisions.
Decisions are accumulated silently during the session and presented for review before commit. This creates a "reasoning changelog" that captures not just what was done, but why.
IMPORTANT: Include constraintViolations when alternatives are rejected due to architectural constraints.
Inputs: type (required), summary (required), repoPath (required), rationale (required), +18 more.
update_featuresA
Update the project's feature catalog from its recorded intents.
Additively groups any intents that are not yet assigned to a feature into the running catalog (an incremental "extend"), without disturbing existing features. The feature catalog is the high-level "what does this project actually do?" view, derived from the repo's intents.
When to use:
After recording or completing intents, to keep the feature list current.
On demand, when you want the catalog refreshed with recent work.
Behavior:
Additive only — never deletes or re-derives existing features.
Intents already assigned to a feature are skipped; only unassigned ones are processed.
Runs in the Kawa Code desktop app and returns the resulting feature count.
Inputs: repoPath (required).
update_intentA
Update an active intent's title, description, scope, or constraints.
Use this to reformulate an intent as understanding evolves during work. Intents are living documents — they should be updated to reflect what the work actually became, not left as the initial guess. Common triggers for reformulation:
The real problem turned out to be different from the initial hypothesis
Scope expanded or narrowed during investigation
The approach changed after discovering constraints
If no intentId is provided, the currently active intent is updated.
Inputs: repoPath (required), scope, title, intentId, +5 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 25 tools
Several tools have overlapping purposes, such as get_intents_for_file and get_intents_for_lines, get_session_decisions and get_project_decisions, and detect_intent_conflicts and pre_edit_decision_check. However, the descriptions generally clarify the specific use cases, reducing ambiguity.
Tool names follow a consistent snake_case convention with verb prefixes (get_, check_, create_, etc.), but there are some inconsistencies like 'check_active_intent' vs 'get_intents_for_file' and 'list_team_intents' vs 'get_intent_changes'. Overall pattern is predictable.
With 25 tools, the set is on the higher end but still appropriate for the server's broad scope covering intent management, decision recording, conflict detection, history inference, and collaboration. Each tool serves a distinct purpose, though some could be consolidated.
The tool set covers the full lifecycle of intents (create, activate, update, complete), decision recording and retrieval, conflict detection, history inference, and feature updates. Minor gaps (e.g., no explicit delete intent tool) but overall comprehensive.
Maintenance
Related MCP Connectors
Coordination for AI coding agents: declare plans, catch design conflicts early, share team memory.
Shared project memory for AI coding agents: decisions, lessons, risks and tasks in one graph.
Shared, scoped, reviewable team memory for AI coding agents.
Memory for AI agent teams across tools, sessions, repositories, and teammates.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceShared team memory for AI coding agents with Bayesian confidence scoring and temporal decay, enabling persistent storage and retrieval of engineering patterns across sessions.20 npm18MIT
- AlicenseNot gradedqualityCmaintenanceFederated, privacy-first shared memory for AI coding assistants that lets you capture, review, and share team knowledge via git without a central server.10 npmApache 2.0
- AlicenseNot gradedqualityDmaintenanceA shared memory and coordination layer for AI coding agents that provides a tamper-evident timeline, conflict awareness, and attribution for multi-agent coding workflows.55 npm8Apache 2.0

Kawa Code MCPofficial
FlicenseAqualityBmaintenanceTeam-aware memory for AI coding assistants that tracks intent, records decisions, and surfaces real-time team conflicts before commit.25-