KumaSafety-first context & orchestration engine for AI coding agents

#Overview

Kuma is a safety-first context & orchestration engine that runs as an MCP server alongside your AI coding agent. Its job is simple: make sure the agent understands what it's about to change before it changes it.

Unlike other MCP tools that give agents more power (editing, searching, executing), Kuma gives agents discipline — a mandatory research pipeline, a knowledge graph of your codebase, impact analysis before every change, and a safety layer that catches mistakes.

Kuma works with any MCP-compatible AI agent: Claude Code, Cursor, Windsurf, Cline, Aider, OpenCode, Codex CLI, and 7 more.

#Quick Start

Run the MCP server

npx -y @plumpslabs/kuma

That's it — zero configuration. The server starts, your agent connects, and Kuma auto-generates .kuma/init.md (behavioral rules) plus a native skill file for your agent.

Generate agent config (optional)

# For all 13 supported agents
npx @plumpslabs/kuma init --all

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

Add to your MCP client

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

#Philosophy

Six principles guide every design decision in Kuma.

#3 Coarse-Grained Tools

Kuma exposes 3 coarse-grained tools with 13 core actions — the agent picks an action, Kuma runs the internal workflow. Everything else was removed: the MCP schema rejects unknown actions.

🧠 kuma_context — Context & Research

📝 kuma_memory — Knowledge Recording

🛡️ kuma_safety — Safety & Verification

#Research Pipeline

The 5-step research pipeline is Kuma's core. It runs every time an agent calls kuma_context({ action: "research" }) — all in a single MCP call. No chaining. No guesswork.

#Workflow

A typical Kuma-powered session follows this pattern:

# 1. Start session — understand the project
kuma_context({ action: "init", goal: "add password reset" })

# 2. Research before touching code
kuma_context({ action: "research", scope: "auth" })

# 3. Agent edits using native tools (not Kuma)

# 4. Save what you learned
kuma_memory({ action: "research_save", scope: "auth", confidence: 0.85 })

# 5. Record significant decisions
kuma_memory({
  action: "decision",
  title: "Use JWT for password reset tokens",
  context: "Need stateless tokens that expire in 15min",
  rationale: "No session store needed, mobile-compatible",
  outcome: "Implemented JwtPasswordResetService"
})

# 6. Safety guard — verify nothing broke
kuma_safety({ action: "guard", guardGoal: "add password reset" })

# 7. Snapshot before risky work (the ONE rollback mechanism)
kuma_safety({ action: "checkpoint", label: "pre-password-reset" })

#Features

#Safety

Kuma's safety layer sits between the AI agent and your filesystem. Every operation is checked, logged, and auditable.

#Checkpoints & Rollback

Kuma provides one rollback mechanism — labeled snapshots. Take a checkpoint before risky work, restore by label if something breaks:

# Snapshot before a risky refactor
kuma_safety({ action: "checkpoint", label: "pre-refactor-auth" })

# Restore if something breaks
kuma_safety({ action: "rollback_label", label: "pre-refactor-auth" })

# Label not found? Kuma lists the available labels

Snapshots capture the SQLite graph + referenced files. If a label isn't found, Kuma lists what's available so you never restore blind.

#Auto-Inject — Shadow Memory

Kuma injects "where is this file fragile and why is it written this way" right before the agent touches it — zero extra steps:

# Claude Code hooks (auto-installed via `kuma init --claude`)
kuma hook pre-edit    # injects gotchas + decisions + history before edits
kuma hook pre-bash    # injects command-triggered gotchas

# Cursor (globs rules, auto-apply on file open)
.cursor/rules/kuma-gotchas/*.mdc

#Storage Layout

Kuma stores per-project data in .kuma/:

.kuma/
├── kuma.db                # SQLite knowledge graph (WASM) — nodes, edges, research cache
├── init.md                # 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
├── KNOWN_GOTCHAS.md       # Gotchas (human-readable layer)
├── ARCHITECTURE_FLOW.md   # Recorded flows (human-readable layer)
├── memories/              # Decision log markdown
│   └── decisions.md       # ADR-style architecture decisions
└── checkpoints/           # Atomic snapshots (label/ with kuma.db + files/)

#API Reference

Full API reference available in docs/api.md.

kuma_context

kuma_memory

kuma_safety

#Architecture — 6 Core Actions

Kuma is memory & safety, not a code manager. The agent uses its own native tools for editing, searching, and execution.

What Kuma Provides

#Comparison