Kairo

Persistent engineering memory and session-continuity for AI coding agents. Local-first. Deterministic. Replay-safe.

Kairo sits between AI coding agents — Claude Code, Cursor, Codex, Gemini CLI — and your repository. It is the layer that remembers: a senior engineer's notebook the agent reads at the start of every session and writes to throughout.

It does not run agents. It does not call a model. It runs next to the agent, on your machine, and gives it the durable memory a model cannot keep on its own.

your repo ──▶ AI agent ──▶ Kairo (MCP) ──▶ .kairo/ on local disk
                  ▲                          │
                  └──── continuation brief ◀─┘
                       (resume, don't rescan)

10-second pitch

AI coding agents forget. Kairo remembers — durably, deterministically, locally.

1-minute pitch

Every new agent session starts by re-deriving the repo: which files exist, which framework, what the entry points are. That's wasteful, slow, and context-window-hostile. Mid-task the agent runs out of context and stops without a clean handoff. The next agent starts from zero.

Kairo records what happens during a session (file changes, decisions, errors, risk assessments), writes durable checkpoints, and hands the next session an exact continuation brief — "here's what was being done, here's where it stopped, here are the files to look at first". Same project, next agent, no rescan.

5-minute pitch — how it works

| Layer | What it does | Where it lives | | ----------------------- | -------------------------------------------------------------- | ------------------------------------- | | MCP server | 42 tools the agent calls during work. | stdio, launched by your MCP host. | | Session ledger | Append-only log of events, decisions, errors. | .kairo/events.jsonl | | Checkpoints | Durable, sanitized, resumable snapshots. | .kairo/checkpoints/*.json | | Continuation briefs | Markdown handoffs in three size modes. | .kairo/continuations/*.md | | Repo intelligence | Cached fingerprint + framework/language/entry-point detection. | .kairo/intelligence/latest.json | | Vector memory | Architecture-aware hybrid recall (deterministic by default). | .kairo/vector/index.json | | Graphs | Mermaid module / service / architecture diagrams. | .kairo/graphs/*.md | | Inspect surfaces | Read-only HTTP + VS Code views. | kairo inspect, extensions/vscode/ |

Every persisted artefact carries a schema version. Reads validate at the storage seam; corrupt lines go to .kairo/quarantine/; migrations are pure functions. The full architecture sits in docs/ARCHITECTURE.md.

Why AI coding breaks at scale (the honest version)

| Failure mode | Why it happens | What Kairo does about it | | --------------------------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------- | | Rescan every session | Agents have no durable scratch space. | kairo_session_start returns cached RepoIntelligence + prior continuation brief. | | Hit context window mid-task | Long sessions exceed any model's window. | Pressure model + CHECKPOINT_NOW directive → safe handoff before crash. | | Repeat past mistakes | Agents don't remember last week's decisions. | Decisions, errors, risk assessments persisted to event log. | | Lose architectural understanding | Agent re-derives layout from scratch. | Pre-computed module + service + architecture graphs available on read. | | No-context handoff between agents | Switching from Claude to Cursor = start over. | Continuation brief works for any MCP-speaking agent. | | Cross-worker conflicts | Two devs/agents touching the same module. | Cooperative file leases (kairo_lease) — explainable, no consensus needed. | | Token cost of "remember everything" | Naive memory layers bloat every prompt. | Brief modes: tiny (1500 chars), normal (4000), deep (20000). |

Kairo is cooperative, not omniscient. It cannot force an agent to stop. It makes losing context expensive and safe handoff cheap. That is achievable and genuinely valuable — and we would rather document the limit than oversell.

What Kairo is NOT

Five boundaries on the front page so they aren't buried in an ADR:

1. Not distributed consensus. Coordination is cooperative-on-shared-storage (file leases over .kairo/), not Paxos/Raft.
2. Not SaaS. No accounts, no hosted backend, no remote telemetry. .kairo/ lives on the local filesystem.
3. Not autonomous AGI orchestration. Kairo is memory + continuity. The agent decides; Kairo records and advises.
4. Not guaranteed semantic truth. Vector recall is hybrid + salience-ranked; the deterministic default is honestly lexical/structural.
5. Not real-time collaborative editing. No streams, no push, no live cursors. Historical inspection + cooperative coordination.

Out of scope by design, not deferred.

Quick start (60 seconds)

In any project:

# 1. Install (globally, so the `kairo` binary lands on PATH)
npm install -g kairo-mcp

# 2. Wire it into your MCP host (Claude Code, Cursor, etc.)
cd your-project
kairo init

# 3. Verify
kairo doctor

Don't want a global install? Use npx -p kairo-mcp kairo init. The -p kairo-mcp flag tells npx "fetch the kairo-mcp package and run the kairo bin from it" — needed because npm packages can have multiple bins and npx <pkg> defaults to the bin matching the package name (which here is the MCP server, not the CLI). Once you've used npx once it's cached; subsequent calls are instant.

Want the pre-release / dev tip? npm install -g github:sandeepbollavaram/Kairo builds from the latest commit on main instead of the published npm version. Same kairo CLI; identical behaviour.

kairo init works in any project type — Node, Python, Rust, Go, empty, anything. It detects your environment and picks the most reliable way to launch the MCP server (since v1.4.0):

| Detected environment | .mcp.json form | When this fires | | ----------------------------------------------- | --------------------------------------------- | --------------------------------------------------------------------- | | ./node_modules/kairo-mcp/dist/index.js exists | node ./node_modules/kairo-mcp/dist/index.js | Node project that ran npm install kairo-mcp locally. | | kairo-mcp on PATH | command: "kairo-mcp" | Any project after npm install -g kairo-mcp (recommended). | | neither | npx -y kairo-mcp | Empty repo, Python repo, no install at all. npx fetches on first run. |

Output looks like:

Initialised
  .mcp.json:   written
  mcp form:    global (kairo-mcp on PATH)
  .gitignore:  appended
  mcp host:    claude

Next steps
  1. Open Claude Code in this project: claude
  2. Inside the session, run: /mcp
     → you should see  kairo · connected · 42 tools
  3. If anything looks off, run: kairo doctor

kairo doctor is your one-stop check:

Doctor
  ok  project root           /your/project
  ok  kairo-mcp installed    ./node_modules/kairo-mcp/dist/index.js
  ok  .mcp.json wires kairo  ./.mcp.json
  !!  .kairo/ present        (none yet — first MCP session creates it)
  ok  quarantine empty       clean
  ok  version match          installed=1.2.0 cli=1.2.0

next: 1 check(s) need attention.

(The .kairo/ warning is expected — the first agent session creates it.)

Open Claude Code in the project, run /mcp, you'll see kairo · connected. Then say "start a Kairo session and help me with X."

Real workflow

$ cd flexdee-monorepo
$ npx kairo init
Initialised
  .mcp.json:   written
  .gitignore:  appended
  mcp host:    claude

Next steps
  1. Open Claude Code in this project: claude
  2. Inside the session, run: /mcp
     → you should see  kairo · connected · 42 tools
  3. If anything looks off, run: kairo doctor

# ── Day 1: open Claude Code, work for an hour, end the session ────────
$ npx kairo status
Project
  root              S:\projects\flexdee-monorepo
  events            47
  telemetry         12
  sessions          1
  checkpoints       2
  quarantine        0
  latest session    01JD8VK7HQM…
  latest checkpoint 01JD8WPCXNE…

Intelligence
  schema     v4
  files      842
  frameworks express, nextjs, prisma
  languages  TypeScript, JavaScript, SQL

# ── Day 2: see exactly what the next agent will resume from ───────────
$ npx kairo brief --tiny
# Kairo Continuation Brief (tiny)

- **Task:** wire idempotent payment retries
- **Stop point:** session-end · risk HIGH · pressure CONTINUE
- **Files changed:** 3 — top: src/payment/charge.ts, src/payment/retry.ts
- **Next:**
  1. Resolve the 1 unresolved error(s) before new feature work.
  1. Re-validate high-risk changes before proceeding: src/payment/charge.ts.
- **Critical warnings:**
  - ⚠️ integration test flakes on retry path

# ── Inspect everything in your browser ────────────────────────────────
$ npx kairo inspect
ready http://127.0.0.1:4173
  project: S:\projects\flexdee-monorepo
  read-only · no network · Ctrl+C to stop

Token reduction example

Same checkpoint, three modes — measured on Kairo's own repo:

| Mode | Chars | % of deep | Use when | | ------------------ | ----: | ----------: | ---------------------------------- | | tiny | 632 | 15% | Pre-empt rescans on cheap startup. | | normal (default) | 2,946 | 71% | Resumes / checkpoints. | | deep | 4,146 | 100% | Explicit historical review. |

$ npx kairo brief --tiny    # 632 chars
$ npx kairo brief           # 2946 chars (normal)
$ npx kairo brief --deep    # 4146 chars
$ npx kairo brief --max-chars 1000  # exactly 1000 chars, truncated cleanly

Truncation is preservation-aware: critical sections (task, stop point, top changed files, next actions, warnings) are front-loaded so tail clipping keeps the load-bearing content.

Continuation example

After a session ends, Kairo writes a markdown brief. The next agent reads it on kairo_session_start instead of re-deriving the repo:

# Kairo Continuation Brief

> Resume from this brief. Do **not** rescan the whole repository —
> inspect only the files listed below unless they prove insufficient.

- **Generated:** 2026-05-21T14:30:00.000Z
- **Checkpoint:** `01JD8WPCXNEPC0G7N4DXKDKMG6` (manual)
- **Context-loss pressure:** 0.21 → CONTINUE

## Task

wire idempotent payment retries

## Engineering risk at checkpoint

**HIGH** (score 0.6875).

- [HIGH] src/payment/charge.ts (modified) is in a high-risk area

## Files changed this session — inspect these first

| File                    | Change   | Risk | Touches |
| ----------------------- | -------- | ---- | ------- |
| `src/payment/charge.ts` | modified | HIGH | 3       |
| `src/payment/retry.ts`  | created  | HIGH | 1       |

## Key decisions

- **Idempotency via request UUID** — prevents double-charges on retry.

## Recommended next actions

1. Resolve the 1 unresolved error(s) before new feature work.
1. Re-validate high-risk changes before proceeding: src/payment/charge.ts.

## Semantic architecture recall

- **checkpoint 01JD8WPCXN…** (session, score 3.119) — salience 0.86, similarity 0.59
- **src/payment** (structural, score 1.71) — runtimeLayer 1, dependencyProximity 0.83

Graph example

$ npx kairo graph module

flowchart TD
  api[src/api] --> payment[src/payment]
  api --> auth[src/auth]
  payment --> shared[src/shared]
  auth --> shared
  payment --> db[(prisma)]

The same file lives at .kairo/graphs/module.md — kairo inspect renders it in the browser via its Mermaid source.

Snapshot / recovery example

# Archive the current state as one portable JSON file:
$ npx kairo snapshot export
  path:        S:\...\flexdee\.kairo\snapshots\snapshot-2026-05-21....json
  bytes:       187,206
  sha256:      df54fa6c84b2a91f3...
  events:      47
  checkpoints: 2
  sessions:    1

# Move it to another machine, then:
$ npx kairo snapshot import ./snapshot.json
  target:        /new/machine/path
  events:        47
  sessions:      1
  checkpoints:   2
  continuations: 2

Snapshots are content-hashed: two exports of the same .kairo/ produce byte-identical files. Use for backups, sharing with teammates for triage, or moving engineering memory between machines.

Multi-agent coordination example

When two agents share a .kairo/, cooperative leases keep them from stepping on each other:

// agent A
{ "name": "kairo_lease", "arguments": {
    "action": "acquire", "scopeKind": "path", "scope": "src/payment"
}}
// → { "granted": true, "reason": "Lease granted on path:\"src/payment\"" }

// agent B (1 minute later)
{ "name": "kairo_lease", "arguments": {
    "action": "acquire", "scopeKind": "path", "scope": "src/payment"
}}
// → { "granted": false, "conflict": {...}, "reason":
//      "Scope path:\"src/payment\" is leased by worker \"agent-A\" until …
//       Coordinate or wait — Kairo advises, it does not preempt." }

This is cooperative, not consensus. Two agents on a shared filesystem observe the same event log and agree to back off. No network protocol, no master. The same model also keeps cross-worker semantic memory namespace- isolated (one agent's private chunks don't leak to another).

VS Code integration

A separate publishable extension under extensions/vscode/. Activity-bar tree views for:

• Overview (counts)
• Sessions (newest first)
• Checkpoints (click → opens the continuation brief)
• Active leases
• Risk escalations

Reads .kairo/ directly via fs — does not spawn the MCP server. Auto-refreshes on changes via vscode.workspace.createFileSystemWatcher.

# Build the extension locally
cd extensions/vscode
npm install && npm run build
# then F5 in VS Code to "Run Extension"

(Cursor: same extension works — Cursor is a VS Code fork.)

Inspect surface

Browser-based read-only inspector. No remote assets. Every route except /atlas* is JS-free with CSP default-src 'none'; /atlas* carries a scoped script-src 'self' policy (see Kairo Atlas). Useful for triage, debugging, demos.

$ npx kairo inspect
ready http://127.0.0.1:4173

Routes: /, /sessions, /sessions/:id, /checkpoints, /checkpoints/:id, /continuations/:name, /timeline, /graphs, /graphs/:kind, /memory, /coordination, /risk, /events, /retrieval/:id, /atlas.

Bind defaults to 127.0.0.1 — loopback only. --host 0.0.0.0 is allowed but not recommended.

Kairo Atlas

Kairo Atlas is a local, read-only interactive architecture map generated from Kairo's deterministic repo intelligence. It helps humans inspect modules, dependencies, risk overlays, and AI-session activity without reading raw JSON or Mermaid files.

npm install -g kairo-mcp
cd your-project
kairo init          # wire Kairo into the project (once)
kairo inspect       # start the local inspector
# open http://127.0.0.1:4173/atlas

Atlas projects the cached module graph, which Kairo produces when it scans the repo. If you've run a Kairo session in the project, the scan already happened; otherwise start a session in your MCP host (or have the agent call kairo_repo_scan), then refresh /atlas.

Screenshots (captured on the Kairo repo itself; committed locally — no remote/CDN images):

2D overview — the full module graph (here Kairo itself: 33 nodes / 147 edges). The large green node is tests; blue nodes are source. Size = salience, colour = group.

Click-to-focus — selecting core/session highlights it and its neighbours (core/checkpoint, core/continuation, core/brief) and dims everything else, so a module's blast radius is obvious.

Top-N + honest truncation — capping to the 25 most-salient nodes shows the truncation banner ("Showing top 25 of 33 nodes by salience").

3D view — the same payload as a self-authored perspective projection (no three.js / WebGL library). Drag to rotate, scroll to zoom, Shift+drag to pan.

Search + filters — typing /co lists matching modules (core/compaction, core/continuation, core/coordination); matched nodes are ringed, and the chip row filters by source/changed/risk/salience/checkpoint/session or hides docs/tests/examples/generated.

What it gives you:

• 2D map (default) — pan / zoom / click; nodes sized by salience, coloured by group, risk rings, changed-by-AI ticks.
• 3D map — rotate / zoom / pan / reset-camera; a self-authored projection, no third-party 3D library.
• Search — / to focus; match by path/module with neighbour highlighting and a results list.
• Filters — hide docs/tests/examples/generated; focus source-only, high-salience, high-risk, changed, checkpoint-related, session-related.
• Node detail panel — salience, centrality, fan-in/out, risk, and clickable incoming/outgoing dependencies to walk the graph.
• Top-N control + an honest truncation banner on large graphs.

Local-first & safe: served from the loopback inspector, read-only, no network, no CDN/remote assets. Only /atlas* relaxes the CSP to script-src 'self' (no unsafe-inline, no unsafe-eval, no remote origins); the backend .kairo/ state stays the source of truth.

Honest scope: Atlas visualizes Kairo's deterministic signals — static import edges collapsed to directory granularity, salience-capped for readability. It does not claim to understand every codebase. Full guide: docs/ATLAS.md · design: ADR-0019.

Atlas Capsule

Kairo Atlas helps humans understand the codebase. Atlas Capsule helps AI agents continue the work.

Atlas Capsule (v1.6.0) is a portable, token-budgeted AI handoff package. When one agent times out or hits its context limit, generate a capsule and paste or export it into the next agent — Claude Code, Codex, Cursor, or any generic AI coding agent — so it continues with significantly less unnecessary rescanning.

Why it exists. Even with repo memory, checkpoints, briefs, Atlas, graphs, and telemetry, a fresh agent session still tends to re-scan large parts of the repository to re-orient, wasting context before any new work starts. Capsule is the missing piece: one trusted bootstrap package that states what is known, what changed, what to read first, and what is safe to skip initially.

How it reduces rescanning. The capsule hands the next agent a risk-ranked read-first plan plus a "safe to skip initially" list (always phrased unless you detect a mismatch), so it starts at the active code instead of walking the tree.

kairo capsule                                    # standard / generic → stdout
kairo capsule --mode tiny                         # urgent handoff (~1.5k chars)
kairo capsule --target codex --mode standard      # Claude → Codex handoff
kairo capsule --target codex --agents-md          # write AGENTS.md (Codex)
kairo capsule --target claude --output capsule.md # write to a file

There is also an MCP tool kairo_capsule_create and a read-only Capsules tab in kairo inspect.

Claude → Codex handoff. When Claude is about to run out of context, run kairo capsule --target codex --mode standard --output handoff.md (or call kairo_capsule_create), then paste handoff.md into Codex — or commit an AGENTS.md via --agents-md (it refuses to overwrite an existing file without --force).

Honest limits. A capsule reduces unnecessary rescanning; it does not stop all rescanning or guarantee no rereads. It is a trusted starting point, not a replacement for validation — agents may still reread files to verify safety. It is a projection of existing state and never mutates .kairo/. Secrets are redacted and only repo-relative paths appear, so a capsule is safe to paste into another agent. Full guide: docs/CAPSULE.md · measured sizes & limits: docs/CAPSULE_DOGFOOD.md.

Architecture (overview)

        ┌─────────────────────────────────────────────┐
        │            AI coding agent                   │
        │   (Claude Code · Cursor · Codex · …)         │
        └──────────────────┬───────────────────────────┘
                           │ MCP (stdio)
        ┌──────────────────▼───────────────────────────┐
        │              Kairo MCP server                 │
        │  42 tools · prompts · resources              │
        └──────────────────┬───────────────────────────┘
                           │
        ┌──────────────────▼───────────────────────────┐
        │      Session / risk / pressure / memory      │
        │  · Reducer (events → state)                  │
        │  · Risk engine                               │
        │  · Pressure model                            │
        │  · Vector memory (hybrid recall)             │
        │  · Coordination (cooperative leases)         │
        └──────────────────┬───────────────────────────┘
                           │
        ┌──────────────────▼───────────────────────────┐
        │   Redaction boundary  (write-side)           │
        │   Validation + migration  (read-side)        │
        └──────────────────┬───────────────────────────┘
                           │
        ┌──────────────────▼───────────────────────────┐
        │     `.kairo/`  (local, append-only, durable) │
        │   events · sessions · checkpoints ·          │
        │   continuations · intelligence · graphs ·    │
        │   vector · reports · audit · telemetry       │
        └──────────────────────────────────────────────┘

10 core design principles (see docs/ARCHITECTURE.md):

1. Cooperative, not omniscient.
2. Event-sourced truth.
3. Redaction is a boundary.
4. Local-first.
5. Seams over implementations.
6. Token efficiency.
7. Surfaces are projections.
8. Schemas are versioned; migrations are pure.
9. Scale is measured, not assumed.
10. Integration boundaries are explicit.

CLI reference

kairo init           Wire Kairo into the current project (.mcp.json + .gitignore).
kairo status         One-screen overview of the project's .kairo/ state.
kairo brief          Print the latest continuation brief.  [--tiny|--normal|--deep|--max-chars N]
kairo continue       Alias for `brief --normal`.
kairo sessions [id]  List sessions, or show one.
kairo checkpoints [id]  List checkpoints, or show one with lineage.
kairo graph [kind]   List graphs, or print one (Mermaid).
kairo search "..."   Semantic memory search.
kairo inspect        Launch the local web inspector on 127.0.0.1:4173.
kairo serve          Run the MCP server on stdio.
kairo snapshot export [path]      Export .kairo/ → single JSON.
kairo snapshot import <path>      Import a snapshot into the current project.
kairo compact [--dry-run] [--days N]   Archive stale events.
kairo benchmark [--iterations N]  Run the deterministic benchmark suite.
kairo doctor         Health-check the project's Kairo install.
kairo stability [id] Lookup the stability tier of any documented surface.
kairo plugins        List plugin manifests under .kairo/plugins/.
kairo completion bash|zsh|pwsh    Print a shell-completion script.
kairo version        Print kairo version.

Every command honours --json, --quiet, --verbose, --no-color, --project PATH, and --help.

MCP surface (v1.2.0)

42 tools total — 35 stable + 7 experimental. The full list:

| Group | Tools | | ------------------------------------------ | ----------------------------------------------------------------------------------------------- | | Continuity loop (stable, v0.1) | session_start session_status record heartbeat checkpoint continuation session_end | | Repository intelligence (stable, v0.2) | repo_scan repo_intel | | Risk (stable, v0.3) | assess | | GitHub-flavoured (stable, v0.4) | git_status commit_message changelog release_plan | | Graphs (stable, v0.5) | graph | | Memory (stable, v0.6+) | memory_search memory_index memory_digest memory_refresh | | Coordination (stable, v0.7) | lease coordination_status timeline | | Telemetry / analytics (stable, v0.8) | telemetry_status analytics_summary team_activity risk_report module_activity | | Query (stable, v0.8.1) | query_events timeline_query checkpoint_lineage conflict_history retrieval_trace | | Briefs (stable, v0.8.2) | brief | | Snapshots (stable, v0.9.2) | snapshot_export snapshot_import | | Experimental (v0.9.3 / v0.9.4) | benchmark perf_report compact_memory index_status plugins_list stability_of |

All tools are prefixed kairo_ over the wire. See docs/API_STABILITY.md for the policy and src/contracts/stability.ts for the registry.

Stability guarantees

Anything tagged stable in src/contracts/stability.ts stays callable with the same shape on every v1.x release. Patch versions never bump a schema. Minor versions may add tools (back-compat) but not remove or rename stable ones without a one-minor deprecation cycle.

Programmatic access:

// SDK
import { KairoClient } from 'kairo-mcp/sdk';
const k = new KairoClient();
k.stabilityOf('kairo_session_start'); // → { tier: 'stable', since: '0.1.0', ... }

# CLI
$ kairo stability kairo_session_start
  id:       kairo_session_start
  surface:  mcp-tool
  tier:     stable
  since:    0.1.0

FAQ

Q: Where does my data live? /path/to/your/project/.kairo/. Nothing leaves the machine. No network egress in core paths.

Q: Do I need to run a server? No. The MCP host (Claude Code, Cursor) launches kairo-mcp per session over stdio. Idle = no process.

Q: Should I commit .kairo/? Default: no — kairo init gitignores it. If your team wants shared engineering memory, leave it tracked; cooperative leases handle conflicts. For lighter sharing, use kairo snapshot export to ship a single JSON.

Q: How do I share state with a teammate?

$ kairo snapshot export ./for-alice.json
$ # send for-alice.json
$ # on Alice's machine:
$ kairo snapshot import ./for-alice.json --force

Records pass through redaction on the way in.

Q: How do I reset?

rm -rf .kairo/

No external state to clean.

Q: Will it slow down my agent? No. Every MCP tool is O(milliseconds) on a typical project. Cold scan is ~6 ms on a small repo, warm scan is sub-millisecond. kairo benchmark measures it.

Q: What if the event log gets corrupted? readValidatedJsonl quarantines the bad line to .kairo/quarantine/ and continues. Healthy events still load. kairo doctor surfaces quarantine count.

Q: What models work with Kairo? Any MCP-speaking agent. Claude Code, Cursor, Claude Desktop, Codex (via its MCP support), Gemini CLI (where supported). The MCP server itself calls no LLM.

Q: What's the licence? MIT. See LICENSE.

Troubleshooting

The most common installation issues, with the one-line fix for each.

/mcp shows kairo · ✘ failed

The MCP host can't launch the kairo-mcp server. Run kairo doctor; it diagnoses the actual cause in five checks.

Most frequent cause (especially in non-Node projects like Python / Rust / Go before v1.4.0): .mcp.json referenced ./node_modules/kairo-mcp/dist/ index.js which doesn't exist in that project type. Fix:

kairo init --force      # v1.4.0+ rewrites .mcp.json with the right form

v1.4.0 picks one of three forms (local / global / npx) based on your environment, so kairo init --force resolves the bad path automatically. See the Quick start table above for what each form does.

kairo: command not found after npm install

You ran npm install kairo-mcp (local) rather than npm install -g kairo-mcp (global). Either:

# Option A: switch to global install (recommended)
npm install -g kairo-mcp
kairo --version

# Option B: keep local install, call via local bin path
./node_modules/.bin/kairo --version

# Option C: no install at all
npx -p kairo-mcp kairo --version

kairo init says mcp host: not detected

kairo init looks for claude on PATH to print host-specific next steps. If your shell can't find it (e.g. inside a Python venv that shadows your global PATH), the field shows not detected. This is informational only — the .mcp.json is still written correctly and Claude Code will pick it up when you open the project. To verify:

where claude      # Windows
which claude      # macOS / Linux

If the command resolves outside the venv but not inside, your venv's activation script is overriding PATH — common with Conda and some pyenv configurations.

MODULE_NOT_FOUND when Claude Code spawns kairo-mcp

You're on a pre-v1.4.0 build that hard-coded the local-install path. Either:

# Update to latest (recommended)
npm install -g kairo-mcp@latest

# Or manually patch .mcp.json to use the global form

Replace the kairo entry in .mcp.json with:

{
  "mcpServers": {
    "kairo": {
      "command": "kairo-mcp",
      "env": { "KAIRO_PROJECT_ROOT": "." }
    }
  }
}

Anything else

Run kairo doctor --json and attach the output to a bug report. The JSON shape is stable across v1.x; we can diagnose from the report.

Roadmap (post-v1.2.0)

Honest list — no marketing, no AGI:

• v1.x minors: HTTP/SSE transport (the seam is in place via createServer()); promotion of validated experimental tools to stable; Cursor-specific integration docs if the field needs them.
• v1.x patches: bug fixes, ergonomic polish, doc improvements.
• v2.0.0 (no timeline): if and only if a stable surface needs to change shape. We expect months between major versions.

Explicitly not on the roadmap:

• A SaaS / hosted version. Out of scope by design (ADR-0011).
• Autonomous-agent orchestration. The agent decides; Kairo records.
• Real-time collaborative editing.

Contributing

1. Fork, branch, work in small slices.
2. Every PR must pass npm run typecheck, npm run lint, npm run format:check, npm test, npm run build.
3. Adding a stable surface? Add it to src/contracts/stability.ts.
4. Schema bumps require a migration in the same PR (ADR-0012).
5. New ADRs go under docs/adr/; numbering is sequential.
6. Honest scope and replay-safety are non-negotiable. If a change cannot be made deterministic, it requires an ADR.

Documentation

| Document | Purpose | | ---------------------------------------------------------------------- | ------------------------------------------------------ | | docs/ARCHITECTURE.md | Design + 10 core principles + roadmap. | | docs/API_STABILITY.md | Stability tiers + deprecation policy. | | docs/SCHEMA.md | Persisted-artefact schemas + migrations. | | docs/SDK.md | Local read-only client. | | docs/PLUGIN_API.md | Plugin manifest contract. | | docs/MCP_COMPATIBILITY.md | What Kairo promises about MCP. | | docs/SURFACES.md | Inspect + VS Code + Cursor. | | docs/CAPSULE.md | Atlas Capsule — portable AI handoff package. | | docs/CAPSULE_DOGFOOD.md | Measured capsule sizes + honest limits. | | docs/TOKEN_EFFICIENCY.md | Brief budgets + compact responses. | | docs/PERFORMANCE.md | Benchmark harness + incremental indexing + compaction. | | docs/V1_READINESS.md | v1.0.0 entry criteria + compatibility matrix. | | docs/RELEASE_AUDIT_v1.0.0-rc1.md | Final pre-v1 audit. | | docs/DOGFOOD_v1.0.0-rc1.md | The operational dogfood cycle. | | docs/adr/*.md | 16 architecture decision records. |

Licence

MIT.