Safety-first context & orchestration engine for AI coding agents.

Works with any MCP-compatible agent: Claude Code, Cursor, Windsurf, Zed, and more.

What is Kuma?

Kuma is an MCP (Model Context Protocol) server that acts as a pre-modification safety layer for AI coding agents. Before an agent touches your code, Kuma enforces a research and safety pipeline — like a pre-flight checklist for code changes.

The Problem: AI agents often modify code without understanding the full context — missing dependencies, breaking related features, or repeating past mistakes.

The Solution: Kuma is a shadow memory that injects "where is this file fragile and why is it written this way" right before the agent touches it:

• 🪄 Auto-inject hooks — gotchas/decisions/history injected before every edit, zero extra steps
• 🧠 Knowledge graph — SQLite-based derived cache (hash-verified, never stale)
• 📝 Decision memory — ADR-style decision tracking across sessions
• 📊 Kuma Studio — Visual dashboard for gotchas, decisions, and shadow-memory metrics

Quick Start

⚡ Universal 1-Liner (Auto-detects your IDE/Agent)

curl -fsSL https://raw.githubusercontent.com/plumpslabs/kuma/main/install.sh | bash

🧩 Or Install as a Native Plugin

• Claude Code Marketplace:

  /plugin marketplace add plumpslabs/kuma
  /plugin install kuma@plumpslabs-kuma

• Antigravity CLI (AGY):

  agy plugin add https://github.com/plumpslabs/kuma

• Via NPX (Zero Install):

  npx @plumpslabs/kuma init --all

📖 See INSTALL.md for the complete provider matrix (Cursor, Windsurf, OpenCode, Copilot, Zed, Cline, Aider, etc.).

Core Architecture: 3 Pipeline-Driven Tools

Kuma exposes 3 coarse-grained tools with 15 core actions — the full agent surface. Anything else (impact, navigate, changes, digest, drift, resume, mine, session, delete_node, clear, goal_progress, check, audit, security, gc, ast, validate, gotcha_staleness) was removed — not hidden, gone — so the agent never has to choose from 30+ options and there is no dead surface to maintain.

🧠 kuma_context — Context & Research

| Action | Purpose | Impact | |--------|---------|--------| | init | Lean project brief + restore session + branch tracking | 🔴 Required first | | research | 5-step pipeline: cache → graph → scan → impact → decision | 🔴 Required before edits | | map | Monorepo package topology & workspace boundary mapping | 🔴 High | | cluster | Concept-level subsystem clusters with typed relationship verbs | 🔴 High | | skeleton | Compressed AST code outline (85-93% token reduction) | 🔴 High | | reuse | Anti-duplication helper discovery before writing new code | 🔴 High | | impact | Blast radius analysis with PageRank centrality scoring | 🔴 High | | history | Why is this file written this way (cross-session trace) | 🔴 High | | flow | Read a recorded architecture flow | 🔴 High |

💾 kuma_memory — Decision & Knowledge

| Action | Purpose | Impact | |--------|---------|--------| | gotcha | Record bugs/quirks + lifecycle (active → resolved → deprecated) | 🔴 Exponential | | arch_flow | Record architecture flow (max 5 core files) | 🔴 Exponential | | decision | Record ADR-style decision with rationale | 🔴 Exponential | | research_save | Save research findings to cache | 🟡 Linear | | search | Quick lookup of memory + knowledge graph | 🟡 Linear |

🛡️ kuma_safety — Safety & Verification

| Action | Purpose | Impact | |--------|---------|--------| | guard | Detect anti-patterns, drift, runaway loops | 🔴 Required | | verify | Post-edit blast radius & affected test targeting (<50ms static resolution) | 🔴 High | | checkpoint | Labeled snapshot before risky work | 🟡 Linear | | rollback_label | Restore a labeled snapshot | 🟡 Linear |

Architecture

Kuma exposes exactly 3 coarse-grained tools — the agent picks an action, Kuma runs the internal workflow:

| Tool | Core Actions | Purpose | |------|--------------|---------| | kuma_context | init, research, map, cluster, skeleton, reuse, impact, history, flow | Load project context, understand unfamiliar code | | kuma_memory | gotcha, decision, arch_flow, research_save, search | Persistent knowledge that saves future sessions | | kuma_safety | guard, verify, checkpoint, rollback_label | Pre-risk guard, post-edit blast radius verification, snapshot/restore |

Everything else is an internal action — not exposed to the agent. The agent uses its own native tools for editing, searching, and execution — Kuma is memory & safety, not a code manager.

What Kuma Provides

• Knowledge Graph — SQLite + FTS5 full-text search (derived cache)
• Session Memory — track tool calls, recordings, and efficiency per session
• Guard System — real-time monitoring with blocking warnings for anti-patterns
• Shadow Injection — gotchas injected before edits via hooks (zero token waste when clean)
• Kuma Studio — visual dashboard with graph, gotchas, and injection metrics
• Checkpoint/Rollback — atomic snapshots before major refactors

Kuma Studio

Kuma Studio is a streamlined, modular web dashboard for visualizing your codebase intelligence, gotchas shield, and workspace topology without visual clutter.

Features

• 🛡️ Gotcha Shield — Filter gotchas by status (active, verified, resolved), severity, and copy workarounds in 1 click
• 🔀 Domain Sequence Flows — Linear architecture hops and execution sequences
• 📦 Workspace & Blast Radius — Monorepo package dependency matrix and real-time blast radius impact simulator
• ⚡ Health & Efficiency — Session metrics, estimated hours saved, verification pass rates, and injection statistics
• 🕸️ Calm Knowledge Graph — Clean node-link visualization with optional physics simulation and depth controls

Usage

# Start Kuma Studio
kuma studio

# Or via npx
npx -y @plumpslabs/kuma studio

Studio runs at http://localhost:3322 and provides:

• Real-time graph visualization
• Copy report functionality for activity analysis
• Node detail modals with relations and gotchas
• Search and filter capabilities
• Physics-based graph layout with depth controls

Knowledge Graph Schema

Kuma builds a comprehensive knowledge graph with these node types:

| Node Type | Description | |-----------|-------------| | feature | High-level module (e.g., Auth, Billing) | | arch_flow | Architecture flow between files | | gotcha | Known bug or quirk | | decision | ADR-style decision with rationale | | function | Function or method | | class | Class definition | | component | UI component | | file | Source file | | api_route | API endpoint | | test | Test file | | research | Research cache entry |

Edge types include: contains, flows_through, owns, explains.

Safety Layer

Audit Trail

Every safety check is logged to the audit trail:

• Tool name and parameters
• Risk level (low/medium/high/critical)
• Allowed/blocked decision
• Duration and metadata

Workflow

A typical Kuma-powered session follows this flow:

1. INIT          → kuma_context({ action: 'init' })
                   Load project brief, restore session context

2. RESEARCH      → kuma_context({ action: 'research', scope: '<area>' })
                   5-step pipeline: cache → graph → impact → decision → safety

3. GUARD         → kuma_safety({ action: 'guard' })
                   Check for anti-patterns, drift, runaway loops

4. EDIT          → Agent modifies code (native tools)

5. RECORD        → kuma_memory({ action: 'gotcha' | 'arch_flow' | 'decision' })
                   Record what was learned for future sessions

6. VERIFY        → kuma_safety({ action: 'verify' })
                   Auto-run scoped tests + validation

7. CHECKPOINT    → kuma_safety({ action: 'checkpoint', label: 'post-<feature>' })
                   Snapshot once stable — restore with rollback_label if needed

Per-Project Context Model

Kuma stores all context locally in .kuma/:

.kuma/
├── kuma.db          # SQLite knowledge graph (WASM) — nodes, edges, research cache, changes
├── init.md          # Project behavioral rules (generated by `kuma init`)
├── memory.json      # Session state + metrics (auto)
├── auto-gotcha.json # Self-learning loop state (auto)
├── policy.yml       # OPTIONAL safety policy — only read if you create it
├── memories/        # Decision log markdown (decisions.md)
├── checkpoints/     # Atomic snapshots (label/ with kuma.db + files/)

Hooks are registered in .claude/settings.json (PreToolUse) — not stored under .kuma/.

Research cache is not a folder — it lives in the research_cache table inside kuma.db.

Key principle: Context is per-project, per-agent. No shared state between projects.

Why Kuma?

| Problem | Without Kuma | With Kuma | |---------|--------------|-----------| | Context | Agent forgets project-specific patterns | Knowledge graph persists across sessions | | Safety | Agent may break critical code | Policy engine blocks risky operations | | Impact | Agent doesn't know what's affected | Impact analysis traces dependencies | | Coordination | Multiple agents conflict | Per-agent session state + audit trail avoid collisions | | Memory | Agent repeats past mistakes | Decision memory + gotchas prevent loops | | Reversibility | Hard to undo changes | Checkpoint snapshots + rollback_label | | Staleness | Knowledge becomes outdated | Drift detection + gotcha staleness checks flag stale data |

Installation

# Global install
npm install -g @plumpslabs/kuma

# Or use npx (no install needed)
npx -y @plumpslabs/kuma

# With pnpm
pnpm add -g @plumpslabs/kuma

Requirements

• Node.js >= 18.0.0
• No native dependencies (uses WASM for SQLite)

CLI Commands

# Start MCP server (default)
kuma

# Start Kuma Studio dashboard
kuma studio

# Initialize a project
kuma init

# Show version
kuma --version

# Show help
kuma --help

Configuration

MCP Client Configuration

Add to your MCP client config (e.g., Claude Desktop):

{
  "mcpServers": {
    "kuma": {
      "command": "npx",
      "args": ["-y", "@plumpslabs/kuma"]
    }
  }
}

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | KUMA_DB_PATH | Custom database path | .kuma/kuma.db | | KUMA_POLICY_PATH | Custom policy file | .kuma/policy.yml | | KUMA_STUDIO_PORT | Studio server port | 3322 |

Development

# Clone the repo
git clone https://github.com/plumpslabs/kuma.git
cd kuma

# Install dependencies
pnpm install

# Build
pnpm run build:all

# Run tests
pnpm test

# Start studio in dev mode
pnpm run studio:dev

Power Curve: What to Record

| What to Record | When | Why | Impact | |----------------|------|-----|--------| | arch_flow | After tracing a complete flow | Saves 5-10 files next session | 🔴 Exponential | | gotcha | IMMEDIATELY when finding bugs | Prevents re-discovery | 🔴 Exponential | | decision | When choosing between options | Preserves rationale | 🔴 Exponential | | feature | When identifying a module | Creates owns edges to files | 🔴 Exponential | | research_save | After exploring an area | Creates search cache | 🔴 Exponential | | Function/class nodes | Skip | Agent can grep/glob | 🟢 Skip | | Import edges | Skip | Agent can read imports | 🟢 Skip | | Visual graph | Skip | For humans, not AI | 🟢 Skip |

License

MIT — use freely in personal and commercial projects.

Community

• GitHub: github.com/plumpslabs/kuma
• Issues: github.com/plumpslabs/kuma/issues
• npm: npm.im/@plumpslabs/kuma