vlm-code-context-mcp

Persistent memory for AI coding agents.

Your agents forget everything between sessions. This fixes that.

npm install vlm-code-context-mcp
npx code-context-mcp setup .
npx code-context-dashboard ./context.db   # optional — live dashboard on :3333

Two commands, then restart Claude Code — setup writes .mcp.json, so the server loads automatically. Zero API keys. One context.db file.

Benchmark

Tested across 10 real development tasks (retrieval, debugging, refactoring, implementation), then validated with 200 randomized trials and a Wilcoxon signed-rank test.

MCP tools return structured summaries (exports, deps, file role) instead of raw file content. Agents read less, know more. (Re-validated for v2.0.0 — and since 2.0, sprint ceremonies themselves cost −39% output tokens via compact-by-default tools, measured on a replayed kickoff.)

# Deterministic — 10 tasks, 6 categories
npm test -- test/benchmark.test.ts

# Stochastic — 200 randomized trials, Wilcoxon test, bootstrap CI
npm test -- test/benchmark-stochastic.test.ts

Full methodology in BENCHMARK-GUIDE.md.

Related MCP server: MCP Local Codebase Search

New in 2.2 — Discipline & Telemetry 📐

• Commit contract, injected and enforced — delegated implementation prompts carry the Why:/What:/How: commit-body contract (derived live from the wf:write-commit-messages skill), and update_ticket refuses qa_verified while a ticket's commits don't follow it — offending hashes named, docs-only tickets exempt, always fail-open.

• Telemetry without ceremony — closing a ticket auto-snapshots the burndown and can log actual_hours against the assigned agent; phase transitions snapshot too. Retros quote real numbers instead of 0h.

• Leaner internals — tools.ts and dashboard.ts both decomposed into domain modules (dashboard server −37%), with byte-identical tool/route surfaces pinned by mutation-verified parity tests.

• Claude Fable 5 tier — dev roles default to claude-fable-5; ticket routing gains the fable tier.

New in 2.0 — Process 2.0 🚦

• Planning gates that close the retro loop — sprints refuse to start while retro try_next learnings sit untriaged; adopt, drop, or defer each one (triage_retro_finding), and adopted items auto-flag as applied when their ticket lands.

• Honest velocity — commitment freezes when implementation starts; mid-sprint scope shows as +added / removed instead of inflating completion rates.

• Terminal cockpit — tools render width-locked progress cards in colored ```diff fences, and the code-context-statusline bin puts a live sprint HUD in Claude Code's status line at zero token cost.

• Live-editable board + session reaction — edit tickets on the dashboard; the Claude session sees a ⚠ CHANGED TICKETS diff block and acknowledges your changes.

• Multi-agent tickets — several agents per ticket with per-assignment model overrides: the lead implements, supporters verify in parallel, QA aggregates the verdicts.

Quick Start

1 · Install

npm install vlm-code-context-mcp

2 · Initialize

npx code-context-mcp setup .

Creates context.db, indexes your codebase, seeds a 9-agent team, seeds the frontend skill library into the project database, writes .mcp.json, and offers to wire the sprint statusline into .claude/settings.json (pass --defaults to skip the prompts). Run it again later and it switches to update mode — migrate (with automatic backup) + config repair, never touching your data; --force renames the old database instead of deleting it.

3 · Restart your AI client

Restart Claude Code (or any MCP client) — it picks the server up from the .mcp.json that setup wrote. Verify with get_project_status.

Registering manually instead? The equivalent is claude mcp add code-context -- node node_modules/vlm-code-context-mcp/dist/server/index.js ./context.db

4 · Launch the dashboard

npx code-context-dashboard ./context.db

Opens at http://localhost:3333 with live SSE updates. File watching + auto-reindex on save are on by default (derived from the indexed files); pass a directory as the 4th argument only to override it — e.g. on a database that has nothing indexed yet:

npx code-context-dashboard ./context.db 3333 .

5 · Run your first sprint

Type in Claude Code:

/kickoff

The orchestrator walks you through vision → discovery → milestone → epics → tickets → sprint → implementation → retro — one question at a time. Smart resume lets you stop and pick up later.

Dashboard

7 pages. Live SSE updates. Zero polling.

Every database mutation triggers an instant refresh via SQLite WAL monitoring. Since 2.0 the board is live-editable — title, description, points, status, and multi-agent assignments (with per-assignment models) — and every edit raises a change flag the Claude session sees and acknowledges at its next context load. Completion stays earned: the UI can never set DONE or qa_verified.

Slash Commands

Type these directly in Claude Code.

/kickoff auto-loads the frontend skill playbook into the session when a sprint has fe-engineer work — pull any skill's full guidance with get_skill.

Skill Sets (server-provided)

The server ships three predefined skill libraries — Frontend (22 skills: React 19 / Vue 3 scaffolding, routing, state, forms, auth, i18n, testing, accessibility, performance, design systems, motion, PWA, plus an editable house-style primer), Landing pages (structure, SEO, lead capture, content audits), and Workflow (write-pull-requests, write-commit-messages).

Unlike a plugin, these are served by the MCP server into your live session, not copied into your repo. /kickoff asks once which sets to enable (frontend is on by default; update_skill_sets changes it any time). When a sprint has fe-engineer work, load_phase_context injects the house-style primer and the enabled skill indexes — workflow skills inject for every implementer; your agent then pulls any skill's full guidance on demand with get_skill({ name }). No restart, no files to manage.

How It Works

Every command follows the same pattern: load context from the database before doing anything.

search_files("auth middleware")       → find the right file
get_file_context("src/auth.ts")      → understand role, exports, dependents
Read("src/auth.ts")                  → only now read the actual code

No agent holds the full project in its context window. They query what they need from a shared SQLite brain and write results back.

┌─────────────────────────────────────────────────────┐
│               Claude Code / MCP Client              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐          │
│  │ /kickoff │  │ /sprint  │  │ /ticket  │  ...     │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘          │
│       └──────────────┼─────────────┘                │
│                      ▼                              │
│              97 MCP Tools                           │
│      (reads · writes · ceremony cards)              │
│                      │                              │
│                      ▼                              │
│  ┌─────────────────────────────────────┐            │
│  │       context.db (SQLite)           │            │
│  │  30 tables · WAL mode · <5ms reads  │            │
│  └──────────────────┬──────────────────┘            │
│                     │ WAL watcher                   │
│                     ▼                               │
│  ┌─────────────────────────────────────┐            │
│  │    React Dashboard (Vite)           │            │
│  │  62 components · SSE live updates   │            │
│  └─────────────────────────────────────┘            │
└─────────────────────────────────────────────────────┘

The Agent Team

9 configurable agents, each with a role, model, and mood score. Dev roles default to the strongest model (claude-fable-5), QA to claude-opus-4-8; the rest use claude-sonnet-4-6.

Add, remove, or swap models through MCP tools or with a single click in the dashboard — and the choice routes execution: during /kickoff and /sprint, each ticket is implemented by a subagent spawned at its assigned agent's model tier (fable/opus/sonnet/haiku).

Since 2.0, tickets can carry multiple agents with per-assignment model overrides: the lead implements, supporting agents verify the diff in parallel from their role's perspective, and the QA gate requires every verdict before a ticket counts as done.

Sprint Process

4 phases with enforced gate checks:

planning → implementation → done → rest

Phases, durations, and gates are fully customizable via update_sprint_config.

Since 2.0, planning is gated: start_sprint and advance_sprint refuse to proceed while untriaged retro try_next findings or escalated open discoveries (P0/P1 older than 3 sprints) exist — triage them, or override explicitly with acknowledge_open_items: true. Retro learnings stop being write-only.

Since 2.2, the QA gate also checks commit discipline: a ticket can't reach qa_verified while its referencing commits lack the Why:/What:/How: body groups — and closes feed the burndown automatically.

Tech Stack

Engine Numbers

Manual MCP Server Setup

If the automatic .mcp.json setup doesn't work:

# Add to current project
claude mcp add code-context npx -y vlm-code-context-mcp ./context.db

# Add globally
claude mcp add --scope user code-context node /path/to/node_modules/vlm-code-context-mcp/dist/server/index.js ./context.db

# Remove
claude mcp remove code-context

Development

# MCP server
npm run dev

# Dashboard (Vite dev server with HMR)
npm run dashboard:dev

License

MIT