# Kuma

> Not a plugin for one agent — an infrastructure layer for ALL agents. Works with Claude Code, GitHub Copilot (Codex), Gemini CLI, Cursor, and any MCP-compatible client.

- **Type:** MCP server
- **Install:** `agentstack add mcp-plumpslabs-kuma`
- **Verified:** Pending review
- **Seller:** [plumpslabs](https://agentstack.voostack.com/s/plumpslabs)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [plumpslabs](https://github.com/plumpslabs)
- **Source:** https://github.com/plumpslabs/kuma

## Install

```sh
agentstack add mcp-plumpslabs-kuma
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

```bash
# 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:

```json
{
  "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 |

```bash
# 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](https://github.com/plumpslabs)
- **Source:** [plumpslabs/kuma](https://github.com/plumpslabs/kuma)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-plumpslabs-kuma
- Seller: https://agentstack.voostack.com/s/plumpslabs
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.