# Kuma
**Safety-first context & orchestration engine for AI coding agents.**
[](https://npm.im/@plumpslabs/kuma)
[](LICENSE)
[](https://nodejs.org)
> 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)
```bash
curl -fsSL https://raw.githubusercontent.com/plumpslabs/kuma/main/install.sh | bash
```
### 𧩠Or Install as a Native Plugin
* **Claude Code Marketplace:**
```bash
/plugin marketplace add plumpslabs/kuma
/plugin install kuma@plumpslabs-kuma
```
* **Antigravity CLI (AGY):**
```bash
agy plugin add https://github.com/plumpslabs/kuma
```
* **Via NPX (Zero Install):**
```bash
npx @plumpslabs/kuma init --all
```
π See [INSTALL.md](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
```bash
# 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: '' })
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-' })
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
```bash
# 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
```bash
# 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):
```json
{
"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
```bash
# 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](https://github.com/plumpslabs/kuma)
- **Issues:** [github.com/plumpslabs/kuma/issues](https://github.com/plumpslabs/kuma/issues)
- **npm:** [npm.im/@plumpslabs/kuma](https://npm.im/@plumpslabs/kuma)
---
Built with π§ by the Kuma community