KumaSafety Engine
GitHub Install
v2.4.13 · Zero-Setup SQLite WASM · Monorepo Aware

The Safety-First Context Engine for AI Coding Agents

Enforce pre-edit research, protect against legacy gotchas, analyze blast radius across monorepo packages, and prevent code regressions — in 3 coarse-grained MCP tools.

Get Started in 30s Core Philosophy

#Overview

Kuma is an autonomous safety-first context & orchestration engine that runs as a zero-native-build MCP server alongside AI coding agents. Its job is simple: make sure agents understand what they are about to change before they change it.

Instead of scattering 30+ micro-tools that confuse agents, Kuma exposes exactly 3 coarse-grained tools: kuma_context, kuma_memory, and kuma_safety. Each tool executes deterministic multi-step internal pipelines backed by a pure WASM SQLite knowledge store.

The Surgeon Analogy: Your AI coding agent is the surgeon. Kuma is the pre-op checklist, the patient history, the X-ray, the sterilizer, and the post-op audit — all running deterministically with zero token waste.

#Quick Start

1. Universal 1-Liner (Recommended)

Auto-detects your workspace platforms (Claude, Cursor, Windsurf, Antigravity, OpenCode) and configures rules, hooks, and MCP servers automatically:

bash
curl -fsSL https://raw.githubusercontent.com/plumpslabs/kuma/main/install.sh | bash

2. Or Install via Native Marketplace / Plugin

🟠 Claude Code Marketplace

Install directly from Claude Code terminal:

/plugin marketplace add plumpslabs/kuma
/plugin install kuma@plumpslabs-kuma

🟣 Antigravity / Gemini CLI

Add as a native Antigravity plugin:

agy plugin add https://github.com/plumpslabs/kuma

3. Zero-Setup via NPX

bash
# Auto-detect your editors & agents
npx @plumpslabs/kuma init

# Or install for all 13 supported agent formats
npx @plumpslabs/kuma init --all

4. Add to your MCP Settings

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

📖 Read INSTALL.md for complete setup guides for Cursor, Windsurf, OpenCode, Zed, Cline, and Copilot.

#Core Philosophy

Safety over Speed

5 seconds slower but safe beats lightning-fast regression. Every modification has a verified safety net.

Research First

Mandatory research pipeline before editing unfamiliar code. Blast radius and consumers are evaluated first.

1 Call = 1 Full Workflow

Coarse-grained pipelines. Exactly 3 MCP tools instead of 30+ granular tools that distract agent attention.

Cross-Session Memory

Gotchas, decisions, and domain flows persist across agent restarts, git branch switches, and subagent forks.

Deterministic Execution

SQLite knowledge graph, package dependency graph, and AST analysis execute locally without flaky LLM calls.

Shadow Memory & Auto-Decay

Fresh gotchas injected only when relevant; stale gotchas auto-deprecated when files are deleted or refactored.

#3 Coarse-Grained Tools

Kuma keeps your agent's MCP tool palette lean and focused. All capabilities are grouped into 3 deterministic tools with high-signal actions:

1. kuma_context — Context & Topology

ActionPurposePipeline Flow
initProject brief & session restoreLoads git branch, workspace package summary, and top-5 budgeted fresh gotchas.
research5-step research pipelineChecks cache, scans codebase, executes graph queries, assesses blast radius risk.
historyCross-session provenanceAnswers "why is this file written this way" — change log, decisions, resolved quirks.
mapRepository workspace topologyMonorepo package map, internal package dependencies, and affected packages.
impactBlast radius & consumersIdentifies downstream consumers, related test files, and architectural risk scoring.
flowDomain sequence flowReads sequence flows connecting entry points to middleware, handlers, and databases.

2. kuma_memory — Knowledge Recording & Lifecycle

ActionPurposeDetails
gotchaRecord or resolve quirksSupports full lifecycle: candidate, active, verified, resolved, deprecated.
arch_flowRecord execution sequenceDomain execution flow (e.g. route.ts → controller.ts → service.ts → db.ts).
decisionADR decision recordingRecords architectural decision rationale, options evaluated, and chosen outcomes.
research_saveSave research findingsStores structured research findings into .kuma/research/ and SQLite cache.
searchHybrid knowledge searchFTS5 full-text + graph traversal + session memory search.

3. kuma_safety — Verification & Guardrails

ActionPurposeDetails
guardAnti-regression & architecture checkBlocks circular dependencies, private package imports, and dangerous shell commands.
verifyScoped monorepo verificationAuto-detects test runners (pnpm, npm, cargo, pytest, go) and runs tests on affected packages only.
checkpointAtomic snapshotCreates a point-in-time file snapshot before major refactors.
rollback_labelDeterministic rollbackRestores files cleanly to a labeled snapshot if refactoring fails.

#Workspace Intelligence & Blast Radius

Modern software projects are rarely single-folder apps. Kuma automatically maps monorepo topologies (pnpm workspaces, npm/yarn workspaces, Cargo, Go) and performs deterministic blast radius analysis:

Monorepo Package Graph

Identifies package boundaries, cross-package dependencies, and package ownership without requiring manual configuration.

Downstream Consumer Analysis

When modifying a core package or shared utility, Kuma instantly computes which downstream packages and test files are affected.

Architectural Boundary Guard

Prevents circular package imports and blocks deep private imports (e.g. importing from package/src/internal instead of the package root).

#Gotcha Lifecycle & Auto-Deprecation

Gotchas are fragile legacy quirks and framework pitfalls. To prevent advice decay, Kuma tracks gotchas through a rigorous lifecycle:

01

Candidate

Generated automatically when an automated verification test fails repeatedly. Quarantined until confirmed.

02

Active & Verified

Confirmed gotchas injected right before an agent touches the fragile file. Budgeted strictly to top-5 to prevent context token bloat.

03

Resolved

Marked fixed when verification passes after code modification, or when an agent resolves it via kuma_memory({ action: "gotcha", status: "resolved" }).

04

Deprecated (Auto-Decay)

When files are deleted or renamed, Kuma's self-healing engine automatically retires obsolete gotchas so they never distract future sessions.

#Multi-Agent Concurrency & Atomic Persistence

Parallel background subagents (auditors, researchers, coding subagents) frequently read and write to the knowledge store concurrently:

Atomic Temp-Rename Writes

Database flushes and session memory writes use atomic file replacement (.tmp.pid.timestamp → renameSync), ensuring zero corruptions under high concurrency.

Git Branch Awareness

Tracks current git branches via git rev-parse. Detects branch switches and informs agents immediately so context remains aligned.

Zero Native Build Friction

Runs everywhere Node.js runs using WebAssembly SQLite (sql.js) — zero node-gyp or C++ compiler toolchain headaches.

#Companion Ecosystem & Governance

Kuma is engineered to provide complete peace of mind whether running standalone or paired with agent governance frameworks:

ScenarioHow Kuma OperatesBenefits
Standalone MCP Injected via kuma init into Claude Code, Cursor, OpenCode, Antigravity, Windsurf, Roo, etc. Enforces the research pipeline, gotcha pre-edit shield, and auto-verification on every turn.
With Matcha Pairs harmoniously with Matcha's cognitive governors (planning gate, reviewer, auditor, cleaner). Kuma's .kuma/ state is exempted from gates, providing persistent knowledge to Matcha's 6 specialized subagents.
In CI / CD Runs automated verification, drift detection, and garbage collection in headless scripts. Ensures that repository documentation and knowledge graphs stay perfectly synced with code changes.