Kuma

Kuma

Zero-setup safety & context runtime for AI coding agents — v2.2.2

[](https://www.npmjs.com/package/@plumpslabs/kuma) [](LICENSE) [](https://nodejs.org/)

Works with 13 AI coding agents — Claude Code, Cursor, Windsurf, GitHub Copilot Editor, Cline, Aider, Antigravity CLI, OpenCode, Codex CLI, Qwen Code, Kiro, OpenClaw, CodeWhale — and any MCP-compatible client.

No manual config needed. Just run npx @plumpslabs/kuma init.

---

Quick Start

# Generate config files for ALL supported AI agents
npx @plumpslabs/kuma init --all

# Or generate for specific agents
npx @plumpslabs/kuma init --cursor --claude --aider

# See all options
npx @plumpslabs/kuma init --help

Or add Kuma MCP server manually to any MCP client:

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

---

Unified Tool Router (10 Groups)

> Kuma consolidates 46+ individual operations into 10 grouped tools. AI agents scan 10 groups instead of 46 tools — simpler, faster, less context.

| Group | Actions | What it does | |-------|---------|-------------| | 🔵 kuma_init | init, conventions, structure | Call first every session — load context, detect stack, show tree | | 🟢 kuma_core | grep, read, edit, batch, lsp | During active coding — search, read, safe edit, create files, LSP queries | | 🟡 kuma_verify | test, review, lint | After every edit — run tests, code review, static analysis | | 🔴 kuma_safety | guard, score, check, policy, risk, dependency, context, audit, stats, override | Safety & risk — anti-patterns, health score, pre-exec check, policy enforcement, impact analysis, dependency guard, snapshots, audit trail | | 🟣 kuma_graph | query, navigate, diagram, investigate, arch, experience, intent | Codebase understanding — query knowledge graph, navigate flows, Mermaid diagrams, auto-investigate, architecture guard, experience patterns, intent paths | | 🧠 kuma_memory | get, search, write, decision, context, heal | Persist/retrieve context — session memory, keyword search, persist knowledge, decisions (ADR), auto-context engine, self-heal graph | | 📊 kuma_analytics | reflect, analytics, health, replay, heatmap, learn, predict, confidence, dna | Session review — on-track detection, stats dashboard, code health, session replay, activity heat map, AI learning, predictive next, confidence score, project DNA | | ⏳ kuma_history | timeline, log, diff | Code history — symbol evolution timeline, commit log, structured diffs | | 🔒 kuma_lock | acquire, release, list, clean | Multi-agent coordination — file-level locks, lock listing, stale cleanup | | ⚙️ kuma_advanced | failure, compress, shadow, collective, marketplace | Maintenance — failure knowledge base, semantic compression, shadow execution simulation, collective VPS sync, marketplace templates |

# Full workflow example
kuma_init({ action: "init" })                                    # Load project context
kuma_core({ action: "grep", query: "handleAuth" })               # Find code
kuma_core({ action: "edit", filePath: "auth.ts", edits: [...] }) # Edit safely
kuma_safety({ action: "guard", goal: "refactor auth" })           # Safety check
kuma_verify({ action: "test" })                                  # Verify didn't break
kuma_analytics({ action: "reflect" })                             # Reflect on progress

---

Supported Agents

kuma init generates native config files for 13 AI coding agents — no manual hunting for file formats:

| # | Agent | Generated Files | Approach | |---|-------|----------------|----------| | 1 | Claude Code | CLAUDE.md | Fallback instructions (plugin via /plugin install is proper) | | 2 | Cursor | .cursor/rules/kuma.mdc | Rule file with YAML frontmatter (alwaysApply: true) | | 3 | Windsurf | .windsurfrules | Static rules file | | 4 | GitHub Copilot Editor | AGENTS.md + .github/skills/kuma/SKILL.md | AGENTS.md + Skill file | | 5 | Cline | .clinerules/kuma.md | Rule file with paths frontmatter | | 6 | Aider | CONVENTIONS.md + .aider.conf.yml | Convention file referenced via read: CONVENTIONS.md | | 7 | Antigravity CLI | .agents/skills/kuma/SKILL.md + .agents/mcp_config.json | Skill + MCP config | | 8 | OpenCode | opencode.json | Plugin config JSON | | 9 | Codex CLI (OpenAI) | AGENTS.md + .codex/config.toml | AGENTS.md + MCP server in TOML | | 10 | Qwen Code | AGENTS.md + settings.json | AGENTS.md + MCP server in JSON | | 11 | Kiro | .kiro/steering/kuma.md | Steering file with YAML frontmatter | | 12 | OpenClaw | skills/kuma/SKILL.md | Skill (loaded on demand) | | 13 | CodeWhale | skills/kuma/SKILL.md + .codewhale/mcp.json | Skill + MCP server config |

> AGENTS.md is a merged file shared by Codex CLI, Qwen Code, and GitHub Copilot Editor — one file, no conflicts.

---

Features

🔍 Context & Understanding

| Feature | Tool / Action | Description | |---------|--------------|-------------| | Smart Grep | kuma_core({ action: "grep" }) | Regex code search with context lines, caching, and .gitignore respect | | Smart File Picker | kuma_core({ action: "read" }) | Read files with chunking strategies: full, smart (signatures + tail), outline (exports only) | | Project Structure | kuma_init({ action: "structure" }) | Tree view of project layout with depth control, folder-only mode, patterns | | Project Conventions | kuma_init({ action: "conventions" }) | Auto-detect framework, test runner, package manager, monorepo workspaces | | LSP Query | kuma_core({ action: "lsp" }) | Go-to-definition, find references, type info, rename symbols via TypeScript Language Server. Falls back to regex when LSP unavailable. | | Code Time Machine | kuma_history({ action: "timeline" }) | Track how a function evolved over time — git blame + commit analysis + design decisions | | Git Log | kuma_history({ action: "log" }) | Structured commit history with file filtering | | Git Diff | kuma_history({ action: "diff" }) | Structured diff with staged/unstaged, ref ranges, context control |

🧠 Knowledge Graph (SQLite)

Everything in Kuma is backed by a SQLite knowledge graph — auto-built, auto-healed, queryable:

| Feature | Tool / Action | Description | |---------|--------------|-------------| | Graph Query | kuma_graph({ action: "query" }) | Query nodes/edges/stats. FTS5 full-text search with graceful fallback | | AI Navigation | kuma_graph({ action: "navigate" }) | Answer "How does login work?" — returns the full call chain | | Autonomous Investigation | kuma_graph({ action: "investigate" }) | Given a problem, auto-discovers the relevant code path + bottleneck | | Mermaid Diagrams | kuma_graph({ action: "diagram" }) | Generate architecture, sequence, impact, ownership, heatmap diagrams | | Living Architecture | kuma_graph({ action: "arch" }) | Auto-detect architecture (clean/layered/hexagonal/MVC), detect violations | | Experience Graph | kuma_graph({ action: "experience" }) | Learn from past sessions — suggests next tools based on success patterns | | Intent Graph | kuma_graph({ action: "intent" }) | Organize by intent, not dependency — suggests optimal paths for a goal | | Self-Healing | kuma_memory({ action: "heal" }) | Auto-detect stale nodes, repair via git history or content hash. Cascading edge cleanup |

✏️ Execution — Make Changes Safely

| Feature | Tool / Action | Description | |---------|--------------|-------------| | Precise Diff Editor | kuma_core({ action: "edit" }) | Search-and-replace with exact → whitespace → fuzzy fallback. Auto-backup before every edit. Dry-run preview, versioned rollback, batch edits (up to 10) | | Batch File Writer | kuma_core({ action: "batch" }) | Create up to 15 files in one call. Path validation before writing | | Static Analysis | kuma_verify({ action: "lint" }) | Run ESLint / TypeScript / Prettier / Ruff — structured output | | Code Reviewer | kuma_verify({ action: "review" }) | Senior-level static analysis. Focus modes: correctness, conventions, security, performance, over-engineering detection |

🧠 Memory

| Feature | Tool / Action | Description | |---------|--------------|-------------| | Session Memory | kuma_memory({ action: "get" }) | Session state tracker — modified files, unresolved failures, tool history | | Memory Search | kuma_memory({ action: "search" }) | Keyword search across tool calls, memory files, errors, dependency graph | | Persist Knowledge | kuma_memory({ action: "write" }) | Save decisions, glossary, architecture notes to .kuma/memories/ | | Decision Memory | kuma_memory({ action: "decision" }) | ADR-style decision recording: context → options → rationale → outcome | | Context Engine | kuma_memory({ action: "context" }) | Auto-inject relevant context — finds files related to a goal via graph distance + recency + failure history |

🛡️ Safety — Stay on Track

| Feature | Tool / Action | Description | |---------|--------------|-------------| | Safety Guard | kuma_safety({ action: "guard" }) | Anti-pattern detection (script patching, bash grep), tool loops, drift (edits without tests) | | Safety Score | kuma_safety({ action: "score" }) | Aggregate 0-100 health score across 9 dimensions: git status, backups, LSP, tests, loops, etc. | | Safety Policy | kuma_safety({ action: "policy" }) | Policy file (.kuma/policy.yml) — never_touch, require_review, require_tests, block_commands | | Risk Prediction | kuma_safety({ action: "risk" }) | Before editing — shows references, test files, API routes affected | | Dependency Guard | kuma_safety({ action: "dependency" }) | Before adding packages — checks existing deps, suggests native JS alternatives | | Context Snapshots | kuma_safety({ action: "context" }) | Save/restore project state before risky operations | | Safety Audit | kuma_safety({ action: "audit" }) | Every tool call recorded in SQLite. Queryable trail with override logging | | Safety Check | kuma_safety({ action: "check" }) | Pre-execution safety check — validates path, policy, dangerous commands |

📊 Analytics & Reflection

| Feature | Tool / Action | Description | |---------|--------------|-------------| | Reflection | kuma_analytics({ action: "reflect" }) | On-track/off-track detection, drift warnings, next action suggestion | | Behavior Analytics | kuma_analytics({ action: "analytics" }) | Session stats — tool calls, edits, test runs, rollbacks, loops prevented | | Code Health Dashboard | kuma_analytics({ action: "health" }) | Project-level health — bug density, test pass rate, rollback rate, fragility scoring | | Session Replay | kuma_analytics({ action: "replay" }) | Replay what AI did in a previous session as a human-readable narrative | | Activity Heat Map | kuma_analytics({ action: "heatmap" }) | Show which parts of the codebase AI works on most | | AI Learning | kuma_analytics({ action: "learn" }) | Auto-prioritize high-usage patterns in the knowledge graph | | Predictive AI | kuma_analytics({ action: "predict" }) | Predict what file/tool AI needs next based on current context | | Confidence Engine | kuma_analytics({ action: "confidence" }) | Estimate how confident AI should be — factors: files read, refs checked, graph completeness | | Project DNA | kuma_analytics({ action: "dna" }) | One-page project fingerprint — architecture, coding style, coupling, risk areas, trends |

⏳ History & Time Machine

| Feature | Tool / Action | Description | |---------|--------------|-------------| | Symbol Timeline | kuma_history({ action: "timeline" }) | "Why does login work this way?" — traces a function's evolution across commits with design decisions | | Commit Log | kuma_history({ action: "log" }) | Structured commit history with file filter | | Git Diff | kuma_history({ action: "diff" }) | Staged/unstaged/ref-range diffs with configurable context |

🔒 Multi-Agent

| Feature | Tool / Action | Description | |---------|--------------|-------------| | File Locking | kuma_lock({ action: "acquire" }) | Prevent multiple AI agents from editing the same file simultaneously | | Lock Management | kuma_lock({ action: "list" }) | See active locks, clean stale ones |

⚙️ Advanced

| Feature | Tool / Action | Description | |---------|--------------|-------------| | Failure Knowledge Base | kuma_advanced({ action: "failure" }) | Every failure saved — type, symbol, solution. Proactive warnings for repeat patterns | | Semantic Compression | kuma_advanced({ action: "compress" }) | Compress large codebases into a semantic graph (type signatures + deps — no boilerplate) | | Shadow Execution | kuma_advanced({ action: "shadow" }) | Simulate changes before applying — virtual typecheck, test prediction, risk assessment | | Collective Intelligence | kuma_advanced({ action: "collective" }) | Sync anonymized patterns to your own VPS — learn from multiple projects | | Knowledge Marketplace | kuma_advanced({ action: "marketplace" }) | Install pre-built graph templates for popular frameworks |

---

Kuma's Promise

Kuma is built for one thing: making sure AI agents don't break your project.

Every tool in Kuma has a safety net built-in — not as an afterthought, but as a core design principle:

| # | When this happens... | Kuma does this... | |---|---|---| | 1 | LSP server is not installed | Falls back to regex — never hard fails | | 2 | An edit breaks something | Rollback to any version — versioned backups, dry-run preview, version list | | 3 | AI loops on a test failure | Circuit breaker stops it — prevents infinite retries after 3 identical failures | | 4 | A file path doesn't resolve | Shows where it looked — CWD vs project root with resolved paths | | 5 | A command is dangerous | Blocks it — rm -rf, git push --force, curl \| bash, plus shell obfuscation detection | | 6 | AI keeps repeating the same tool | Tool-loop detection — flags if same tool called 4+ times in last 10 calls | | 7 | You need to undo an edit | Versioned rollback — action: "rollback" with version: N or version: "list" | | 8 | A diff doesn't match | Fuzzy fallback — exact → whitespace-normalized → fuzzy match with configurable threshold | | 9 | AI needs to understand complex code | Knowledge graph — SQLite-backed, auto-built, queryable, self-healing | | 10 | AI is about to break architecture | Architecture guard — detects layer violations, suggests correct dependency direction | | 11 | AI has no context for a goal | Auto-context engine — finds relevant files via graph distance + recency + failure history | | 12 | AI needs to know confidence | Confidence engine — 0-100 score based on context completeness | | 13 | AI wants to know a file's history | Code time machine — shows why code is the way it is via git blame + commit analysis | | 14 | Multiple agents edit the same file | File lock — prevents conflicts, clean stale locks |

Most tools make AI smarter. Kuma makes AI not break things.

---

Safety

| Feature | What it does | |---------|-------------| | Sandboxed | All file operations locked to project directory. Path traversal blocked. System dirs protected. | | Auto-backup | .kuma/backups// snapshot before every precise_diff_editor edit. Rollback to any version. | | Circuit breaker | Stops after 3 identical failures. Prevents AI loops. | | Timeout | All commands have configurable timeout (max 180s). Process tree kill on timeout. | | **

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: plumpslabs
• Source: plumpslabs/kuma
• License: MIT

Install and usage instructions live in the source repository linked above.