Vlm Code Context Mcp

vlm-code-context-mcp

Persistent memory for AI coding agents.

Your agents forget everything between sessions. This fixes that.

[](LICENSE) [](https://www.npmjs.com/package/vlm-code-context-mcp) [](https://www.npmjs.com/package/vlm-code-context-mcp)

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 | Vanilla | Saved | |---|---|---|---| | Tokens | 4,806 | 8,726 | 44.9% | | Tool calls | 49 | 68 | 27.9% | | Stochastic win rate | — | — | 90.5% (p

Reproduce it yourself

# 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](BENCHMARK-GUIDE.md).

---

New in 2.4 — Roster Control 🎛️

• update_agent — change a role's model, tools, system prompt, name, description or department from a single MCP call, and the reply names the Task-tool tier the new model routes to. No raw SQL and no dashboard detour. The sprint instructions used to advertise a create_agent tool that never existed; they now point here.
• One model catalog — claude-opus-5 is offered and accepted everywhere, and seeds the QA role. KNOWN_AGENT_MODELS is the single source of truth the dashboard re-exports, so server and UI can no longer drift; claude-opus-4-8 joins claude-sonnet-4-6 as a legacy id that still renders and edits.
• assigned_to is validated — a model or provider name such as opus or glm used to find no agent and route silently to the sonnet fallback. Both ticket tools now reject anything that is not a roster role and point at impl:* tags for the runtime.

---

New in 2.3 — Current-Gen Models & Hardening 🧭

• Sonnet 5 defaults — support roles seed on claude-sonnet-5; the dashboard offers the full current generation (Fable 5 / Opus 4.8 / Sonnet 5 / Haiku 4.5) from one shared model catalog, and Fable agents finally render (and are pickable) everywhere.
• Reset tools un-broken — reset_agents/reset_skills no longer crash with require is not defined, and a reset preserves agent departments.
• Backups you can trust — --force checkpoints the WAL before renaming and uses SQLite-pairable backup names, so the .bak alone holds every committed write.
• Groomed fatal errors — a DB from a newer version refuses the boot with a clean two-line error (no stack trace, no stray -wal/-shm files), and --help finally tells the truth about setup-vs-update.

---

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.

| Page | What it shows | |---|---| | Dashboard | Kanban board, phase gate stepper, burndown, velocity, sprint checklist | | Planning | Milestone tracker, epic progress, discovery pipeline | | Code | File tree, dependency graph, export/import map, change history | | Team | Agent cards, model badges, mood trends, workload bars | | Retro | Bento grid insights, cross-sprint patterns, recurring themes | | Benchmark | MCP vs Vanilla comparison with animated metrics | | Velocity | Sprint-by-sprint trends, committed vs completed |

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.

| Command | What it does | |---|---| | /kickoff | Full guided lifecycle — vision to retro. Start here. | | /sprint | Sprint-only loop — plan → implement → QA → retro → archive | | /ticket | Move tickets through their lifecycle with full context | | /milestone | Create, update, close milestones with epic verification | | /retro | Data-backed retrospectives with burndown + velocity analysis | | /sprint-connect | Bridge the dashboard UI to your Claude session |

> /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.

| | | |---|---| | Source | claude_development_skills — vendored under vendor/skills/ (build input) | | Storage | seeded into the project DB skills table (fe:*, la:*, wf:*); edit them to make them yours — re-seeds never overwrite your edits | | Opt-in | /kickoff Phase 1b asks once; update_skill_sets({ landing: true, ... }) any time | | Trigger | fe/la on fe-engineer tickets, wf on any implementation work during /kickoff | | Load | index + primer up front; full body via get_skill({ name }) | | Update | boot-time auto-sync from the latest upstream release; npm run sync:skills re-vendors the offline fallback |

---

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-5; the rest use claude-sonnet-5. Change a model, tools or system prompt with the update_agent MCP tool or in the dashboard.

| Role | Focus | |---|---| | Product Owner | Vision, priorities, stakeholder alignment | | Team Lead | Coordination, code review, quality | | Architect | System design, technology decisions, structural integrity | | Backend Developer | APIs, database, server logic | | Frontend Developer | Dashboard components, UI/UX | | Developer | Full-stack features across frontend and backend | | QA Engineer | Testing, verification, quality gates | | Security Engineer | Vulnerability review, threat modeling, security best practices | | DevOps | CI/CD, builds, deployment |

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

| Phase | Duration | Gate | |---|---|---| | Planning | 1 day | Tickets assigned, velocity committed | | Implementation | 3 days | All tickets DONE or NOT_DONE, blockers resolved | | Done | 0.5 day | Retro findings recorded, QA verified | | Rest | 0.5 day | Automatic after retro |

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

| Layer | Technology | |---|---| | Runtime | Node.js 24 LTS | | Database | SQLite via better-sqlite3, WAL mode | | MCP protocol | @modelcontextprotocol/sdk | | Dashboard | React 19 + Vite + Zustand + Framer Motion | | Styling | CSS variables + Tailwind, dark theme | | Live updates | SSE via WAL file watcher | | Testing | Vitest | | Build | TypeScript strict mode |

---

Engine Numbers

| Component | Count | |---|---| | MCP tools | 97 | | Database tables | 32 (27 scrum + 5 code) | | React components | 75 | | Tests | 762 (677 backend + 85 frontend) | | Agent roles | 9 (configurable) | | Sprint phases | 4 with gate checks + planning gate | | Slash commands | 6 | | CLI bins | 3 (code-context-mcp, code-context-dashboard, code-context-statusline) |

---

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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: VelimirMueller
• Source: VelimirMueller/vlm-code-context-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.