Integrates ESLint for linting via the static_analysis tool, parsing output into structured results.
Provides tools for viewing commit history and diffs, and includes safety measures like blocking dangerous git commands such as git push --force.
Integrates with npm for package management detection in project conventions and blocks dangerous npm publish commands.
Supports pnpm via workspace detection in monorepo awareness features.
Integrates Prettier for code formatting checks via the static_analysis tool.
Integrates Ruff for Python linting via the static_analysis tool.
Runs TypeScript static analysis (type checking) via the static_analysis tool and provides LSP-based queries with regex fallback.
Supports Yarn via workspace detection in monorepo awareness features.
Safety-first context & orchestration engine for AI coding agents.
Works with any MCP-compatible agent: Claude Code, Cursor, Windsurf, Zed, and more.
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 ensures every modification is informed by:
🧠 Project-specific knowledge graph — SQLite-based graph of nodes, edges, gotchas, and decisions
🔍 Mandatory research pipeline — 5-step context gathering before any edit
🛡️ Safety policies — Configurable rules that block risky operations
📝 Decision memory — ADR-style decision tracking across sessions
🔄 Self-healing — Automatic detection and repair of stale knowledge
↩️ Selective undo — Symbol-level change tracking for precise reverts
📊 Kuma Studio — Visual dashboard for knowledge graph, efficiency metrics, and activity tracking
Related MCP server: Code Executor MCP Server
# Run with npx (zero setup)
npx -y @plumpslabs/kuma
# Or install globally
npm install -g @plumpslabs/kuma
kumaKuma auto-generates:
.kuma/init.md — Project-specific behavioral rules
.kuma/kuma.db — SQLite knowledge graph (WASM, zero native build)
.kuma/policy.yml — Customizable safety policies
.skills/ — Skill files for common patterns
Kuma V3 consolidates 46+ micro-tools into 3 coarse-grained tools. Each action triggers an internal multi-step workflow — the agent doesn't chain individual calls.
kuma_context — Context & ResearchAction | Purpose | Impact |
| Load project brief, restore session | 🔴 Required first |
| 5-step pipeline: cache → graph → impact → decision → safety | 🔴 Required before edits |
| Analyze change effects on related code | 🔴 High |
| Trace code flow across files | 🟡 Linear |
| View change log for current session | 🟡 Linear |
| Project health score (0-100) | 🟡 Linear |
| Undo a specific change by ID | 🟡 Linear |
| Unified batch state query | 🟢 Skip (agent native) |
| Ultra-compact <500 token project briefing | 🟡 Linear |
| Detect memory staleness & code drift | 🟡 Linear |
| Progressive context loading | 🟡 Linear |
kuma_memory — Decision & KnowledgeAction | Purpose | Impact |
| Save research findings to cache | 🔴 Exponential |
| Record bugs/quirks IMMEDIATELY | 🔴 Exponential |
| Record architecture flow (max 5 core files) | 🔴 Exponential |
| Record ADR-style decision with rationale | 🔴 Exponential |
| Record high-level feature with owns edges | 🔴 Exponential |
| Mine git history for hidden decisions | 🟡 Linear |
| View session summary | 🟢 Skip |
| Repair stale graph entries | 🟡 Linear |
| Search knowledge graph | 🟡 Linear |
| Manage persistent todos | 🟡 Linear |
| Inject notes into context | 🟡 Linear |
| Capture/diff performance metrics | 🟡 Linear |
| Layer 1: Business rules | 🟡 Linear |
| View all 3 memory layers | 🟢 Skip |
kuma_safety — Safety & PolicyAction | Purpose | Impact |
| Detect anti-patterns, drift, runaway loops | 🔴 Required |
| Auto-run scoped tests + AST validation | 🔴 High |
| Pre-execution safety check | 🟡 Linear |
| Query safety audit trail | 🟡 Linear |
| Multi-agent coordination lock | 🟡 Linear |
| Safety health score | 🟡 Linear |
| Bypass safety (recorded in audit) | 🟡 Linear |
| Scan for leaked secrets | 🟡 Linear |
| Garbage collect stale data | 🟢 Skip |
| Full health check | 🟡 Linear |
| Policy-as-Code engine | 🟡 Linear |
| AST-based code validation | 🟡 Linear |
| Atomic snapshot before refactors | 🟡 Linear |
| Restore from checkpoint | 🟡 Linear |
| Pre/post-condition checks | 🟡 Linear |
Kuma V3 is a major evolution focusing on simplicity, safety, and agent-native workflows.
Dropped Tool | Why Dropped |
| Agent has native edit tools |
| Agent executes commands natively |
| Agent searches natively (ripgrep, semantic) |
| Agent creates files natively |
| Merged into |
| Merged into |
Feature | Description |
3 Coarse-Grained Tools | Simplified API: |
Pipeline-Driven Actions | Each action triggers internal multi-step workflows |
Knowledge Graph | SQLite + FTS5 full-text search with WASM engine |
Feature Recording | Auto-detect and record high-level features with |
Session Memory | Track tool calls, recordings, and efficiency per session |
Guard System | Real-time monitoring with blocking warnings for anti-patterns |
Self-Healing | Automatic detection and repair of stale nodes |
Kuma Studio | Visual dashboard with graph, efficiency, and activity tracking |
Policy-as-Code | Configurable safety rules in |
Checkpoint/Rollback | Atomic snapshots before major refactors |
Kuma Studio is a web-based dashboard for visualizing and managing your knowledge graph.
📊 Knowledge Graph — Interactive node-edge visualization with physics simulation
⭐ Features — High-level module tracking with owns edges to files
⚠️ Gotchas — Known bugs and quirks with severity levels
💚 Health — Project health scores over time
⚡ Efficiency — Session metrics, time saved, verification pass rates
📈 Staleness — Detection of stale nodes with missing file references
🤖 Activity — Agent usage intensity, success rates, and session history
# Start Kuma Studio
kuma studio
# Or via npx
npx -y @plumpslabs/kuma studioStudio 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
Kuma builds a comprehensive knowledge graph with these node types:
Node Type | Description |
| High-level module (e.g., Auth, Billing) |
| Architecture flow between files |
| Known bug or quirk |
| ADR-style decision with rationale |
| Function or method |
| Class definition |
| UI component |
| Source file |
| API endpoint |
| Test file |
| Research cache entry |
Edge types include: calls, imports, defines, tests, routes, implements, extends, depends_on, owns, modified_by, contains, composes, flows_through, triggers, syncs_with, affects.
Configure safety rules in .kuma/policy.yml:
rules:
- name: "No production databases"
pattern: "DROP TABLE|DELETE FROM.*WHERE 1"
action: block
message: "Production database modifications blocked"
- name: "Require tests before deploy"
pattern: "git push"
require: "kuma_safety({ action: 'verify' })"
message: "Run tests before pushing"Every safety check is logged to the audit trail:
Tool name and parameters
Risk level (low/medium/high/critical)
Policy violations
Allowed/blocked decision
Duration and metadata
Prevent conflicts when multiple agents work on the same project:
kuma_safety({ action: 'lock', acquire: true })
# ... work ...
kuma_safety({ action: 'lock', release: true })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 + AST validation
7. REVIEW → kuma_context({ action: 'changes' })
Review what was modified this sessionKuma stores all context locally in .kuma/:
.kuma/
├── kuma.db # SQLite knowledge graph (WASM)
├── init.md # Project-specific behavioral rules
├── policy.yml # Safety policies
├── memory.json # Session metrics and recordings
├── research/ # Research cache files
├── memories/ # Memory layer files (domain_rules, arch_flow, gotcha)
└── checkpoints/ # Atomic snapshots for rollbackKey principle: Context is per-project, per-agent. No shared state between projects.
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 | Multi-agent lock prevents collisions |
Memory | Agent repeats past mistakes | Decision memory + gotchas prevent loops |
Reversibility | Hard to undo changes | Selective undo at symbol level |
Staleness | Knowledge becomes outdated | Self-healing detects and repairs stale data |
# Global install
npm install -g @plumpslabs/kuma
# Or use npx (no install needed)
npx -y @plumpslabs/kuma
# With pnpm
pnpm add -g @plumpslabs/kumaNode.js >= 18.0.0
No native dependencies (uses WASM for SQLite)
# Start MCP server (default)
kuma
# Start Kuma Studio dashboard
kuma studio
# Initialize a project
kuma init
# Show version
kuma --version
# Show help
kuma --helpAdd to your MCP client config (e.g., Claude Desktop):
{
"mcpServers": {
"kuma": {
"command": "npx",
"args": ["-y", "@plumpslabs/kuma"]
}
}
}Variable | Description | Default |
| Custom database path |
|
| Custom policy file |
|
| Studio server port |
|
# 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:devWhat to Record | When | Why | Impact |
| After tracing a complete flow | Saves 5-10 files next session | 🔴 Exponential |
| IMMEDIATELY when finding bugs | Prevents re-discovery | 🔴 Exponential |
| When choosing between options | Preserves rationale | 🔴 Exponential |
| When identifying a module | Creates owns edges to files | 🔴 Exponential |
| 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 |
MIT — use freely in personal and commercial projects.
GitHub: github.com/plumpslabs/kuma
This server cannot be installed
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
The WAF for agents. Pattern-based + heuristic firewall scans prompts, RAG documents, tool argume...
See, price, and control every tool call your AI agents make: policy checks, cost, and audit tools.
Lints + auto-fixes how AI coding agents discover any new product. 24 rules, 6 tools, score 0-100.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/plumpslabs/kuma'
If you have feedback or need assistance with the MCP directory API, please join our Discord server