Skip to main content
Glama

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). Without gh, 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 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/<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_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:

when

the agent

your card

within 24h

re-checks the pendingId as it works

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.

  1. 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.

  2. 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.

  3. Hand over a one-line prompt, e.g. Follow up on intent <intent-id>: <what's left to do>.

  4. 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), call resume_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:

  1. Recall before porting each slice. Call get_relevant_context against 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.

  2. Expand what matters. Recall returns summaries — call get_decision_detail on the load-bearing hits for the full rationale and consequences.

  3. 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.

  4. 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.

  5. 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

estimateOnly

true

Preview cost without running. Set false to execute.

commits

resume

How many recent commits to analyze. Omit to continue from the last run.

commitRange

—

Git revspec (sha1..sha2, branch1..branch2, sha1^!) for a specific window. Mutually exclusive with commits. Good for backfilling a PR or recovering a dropped batch.

contextIssues

false

Pull in PR/MR descriptions and issue discussions. Needs an authenticated gh or glab; silently skipped otherwise.

allowCommitSplitting

false

Enable when one commit often mixes unrelated changes.

maxStories

—

Per-run cap on stories analyzed.

model

—

Affects the estimate only. The run's model is configured in the Kawa Code app.

force

false

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_decisions tool. It has been removed: it required a stories array 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 of infer_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_features MCP 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 start

Testing the MCP Server

To test the MCP server without integrating it into an AI assistant:

  1. Build the project: npm run build

  2. Run the server: npm start

  3. The server communicates via stdio (standard input/output)

  4. You can send MCP protocol messages via stdin to test tool functionality

Development Tips

  • Use npm run dev to auto-rebuild during development

  • Check 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 encryption

Contributing

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 tools
activate_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:

  1. Update the intent status (committed/pushed/done/abandoned)

  2. Store the commit SHA for tracking

  3. 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:

  1. 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.

  2. 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.

  3. 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:

  1. Summarize what the user is asking for

  2. Ask the user to confirm the intent details (title, description, type)

  3. 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_history in story-only mode (rare — infer_history already 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 previous infer_history run.

  • 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 (the id / decisionId from 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); call get_decision_detail(decisionId) for the full rationale/context/consequences of any decision you want to open.

Recommended sequence:

  1. check_active_intent at session start to resume any existing work.

  2. Briefly explore the user's request to identify involved files.

  3. get_relevant_context with the prompt and activeFiles to 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 commits value is provided).

Inputs of note:

  • estimateOnly (default true): returns a token/cost estimate without running. Call with estimateOnly: true first to preview cost, then re-call with estimateOnly: false to 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 with commits. 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 (gh or glab) 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 needsDecision instead of running — re-running blind there risks duplicate intents. Present the reason to the user and, if they confirm, re-call with force: true. Run on the default branch (main/master) whenever possible; inferring a feature branch is what force is 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

    A3.9/5.0

    Scored across 25 tools

    Disambiguation3/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers