<div align="center">

<img src="https://raw.githubusercontent.com/plumpslabs/kuma/main/public/kuma.png" alt="Kuma Logo" width="180" />
</div>
# Kuma

**Safety-first context & orchestration engine for AI coding agents.**

[![npm](https://img.shields.io/npm/v/@plumpslabs/kuma?color=amber)](https://npm.im/@plumpslabs/kuma)
[![license: MIT](https://img.shields.io/badge/license-MIT-amber.svg)](LICENSE)
[![node: >=18](https://img.shields.io/badge/node->=18-amber.svg)](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: '<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 + validation

7. CHECKPOINT    → kuma_safety({ action: 'checkpoint', label: 'post-<feature>' })
                   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)

---

<p align="center">
  <sub>Built with 🧠 by the Kuma community</sub>
</p>