code-context-mcp
Health Warn
- License — License: MIT
- Description — Repository has a description
- Active repo — Last push 0 days ago
- Low visibility — Only 5 GitHub stars
Code Fail
- rm -rf — Recursive force deletion command in .github/workflows/pages.yml
Permissions Pass
- Permissions — No dangerous permissions requested
No AI report is available for this listing yet.
MCP server that indexes codebases into a SQLite database, exposing file metadata, exports, dependency graphs, and per-file change tracking.
Read less. Know more.
█████ ████ █████ ██████
██ ██ ██ ██ ██ ██
██ ██ ██ ██ ██ █████ █████
██ ██ ██ ██ ██ ██
█████ ████ █████ ██████
█████ ████ ██ ██ ██████ ██████ ██ ██ ██████
██ ██ ██ ███ ██ ██ ██ ████ ██
██ ██ ██ ██████ ██ █████ ██ ██
██ ██ ██ ██ ███ ██ ██ ████ ██
█████ ████ ██ ██ ██ ██████ ██ ██ ██ ██
// 01 WHAT IT DOES
- Gives AI coding agents persistent memory. Your agents forget everything between sessions. This fixes that.
- Indexes your codebase into one SQLite file,
context.db. Agents query file roles, exports and dependents instead of reading raw files: about 45 % fewer tokens in the benchmark below. - Runs a full sprint process for a 9-agent team: vision, discovery, milestones, epics, tickets, gates and retros, through 93 MCP tools and 6 slash commands.
- Shows everything on a live React dashboard at
:3333. Zero API keys.
// 02 QUICK START
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.
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.
// 03 HOW IT WORKS
agent · Claude Code or any MCP client
│ search_files · get_file_context · find_symbol · /kickoff · /sprint
▼
┌────────────────────┐ stat + git diff ┌────────────────────┐
│ MCP server │ ──────────────────▸ │ your repo │
│ 93 tools │ ◂────────────────── │ git ls-files only │
│ compact cards │ re-index changed └────────────────────┘
└─────────┬──────────┘
│ reads · writes
▼
┌────────────────────┐ WAL watcher ┌────────────────────┐
│ context.db │ ──────────────▸ │ dashboard :3333 │
│ SQLite, WAL mode │ ◂────────────── │ live-editable │
└────────────────────┘ ticket edits └────────────────────┘
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 │ ... │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ └──────────────┼─────────────┘ │
│ ▼ │
│ 93 MCP Tools (99 with all toolsets) │
│ (reads · writes · ceremony cards) │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────┐ │
│ │ context.db (SQLite) │ │
│ │ 30 tables · WAL mode · <5ms reads │ │
│ └──────────────────┬──────────────────┘ │
│ │ WAL watcher │
│ ▼ │
│ ┌─────────────────────────────────────┐ │
│ │ React Dashboard (Vite) │ │
│ │ 62 components · SSE live updates │ │
│ └─────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘
// 04 USAGE
Benchmark
Simulated, not live sessions: 10 scripted development tasks (retrieval, debugging, refactoring, implementation) replayed against an 11-file fixture project, with token counts estimated from what each approach reads — no model calls. A stochastic run of 200 randomized trials with a Wilcoxon signed-rank test checks the result is not a fluke. Method and limits: BENCHMARK-GUIDE.md.
| MCP | Vanilla | Saved | |
|---|---|---|---|
| Tokens (estimated) | 4,806 | 8,726 | 44.9% |
| Tool calls | 49 | 68 | 27.9% |
| Stochastic win rate | — | — | 90.5% (p < 0.001) |
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.
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 |
/kickoffauto-loads the frontend skill playbook into the session when a sprint hasfe-engineerwork — pull any skill's full guidance withget_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 | opt-in boot-time sync from the latest upstream release (CODE_CONTEXT_SKILLS_AUTOSYNC=1); npm run sync:skills re-vendors the offline fallback |
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 | 93 by default, 99 with CODE_CONTEXT_TOOLSETS=all |
| Database tables | 33 (27 scrum + 6 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
// 05 STATUS
| 🟢 Stable | 2.8.0 on npm (the npm badge shows the live version) |
| Tests | npm test (backend) · npm run test:all (backend + frontend) |
| Changes | CHANGELOG.md |
Release highlights
New in 2.8 — Python in the Index 🐍
find_symboland the dependency graph work for Python repos..py/.pyifiles now getexportsrows anddependenciesedges: module-leveldef/async def,classandUPPER_CASE =constants, with the first docstring line as description._-prefixed names are skipped unless__all__lists them;__all__filters the list.- Imports resolve inside the repo.
import a.b,from .mod import x, multi-linefromimports andfrom . import modresolve to<path>.pyor<path>/__init__.pyfrom the repo root orroot/src; stdlib and third-party imports land inexternal_imports. Regex-based like the JS/TS parsers, no new dependencies; JS/TS behaviour is unchanged. - Skill sync follows the claude_development_skills 0.7.0 layout. The
workflowset now readsskills/core/(names staywf:*), so thewf:rows no longer freeze at 0.6.0.scripts/sync-skills.mjsvendors only the cataloguesskill-set-registry.jsonnames.
New in 2.7 — Archive Milestones & Epics 🗄️
- Done is out of sight — completed milestones and epics can be archived like sprints:
update_milestone/update_epictakearchived: true(force: truefor unfinished work), andarchived: falsebrings them back. - Lists stay short —
list_epicsand the newlist_milestoneshide archived rows unlessinclude_archived: true; the Planning page tucks them into a collapsed Archived section with one-click Archive / Unarchive. - Safe upgrade — schema v24 only adds a nullable
archived_atcolumn to both tables; nothing existing is archived.
New in 2.6 — Fresh Index 🧊
- Answers are checked against the disk.
search_files,find_symbolandget_file_contextstat every row they return: a changed file is re-indexed and a deleted one dropped before the answer goes out, and each row carries itsindexed_at. Per repo, a moved gitHEADre-indexes exactly the filesgit diff --name-only <indexed>..HEADlists and says so in one⚠ STALEline; above 500 changed files it warns on every call instead of blocking. - Only your code is indexed. Git checkouts are listed with
git ls-files(every.gitignore, at any depth), on top of a hard deny:node_modules,vendor,dist,build,.next,coverage, Laravelstorage/, dot-dirs (.git,.worktrees), lockfiles, minified bundles, source maps, binaries, files over 512 KB (CODE_CONTEXT_MAX_FILE_KB). code-context-reindexre-indexes every repo under a root:[--all | <repo>…] [--root <dir>] [--db <file>] [--prune-missing] [--vacuum]. A.code-context-ignorefile in a repo keeps it out (and purges its rows). Exit 0/1.- Fewer tools in context. The gamification (
record_mood,get_mood_trends,generate_vision_animation) and the dashboard live-output stream (send_step_progress,send_claude_output,send_claude_step) are hidden unlessCODE_CONTEXT_TOOLSETS=fun,stream(orall). No data is removed.
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 acreate_agenttool that never existed; they now point here.- One model catalog —
claude-opus-5is offered and accepted everywhere, and seeds the QA role.KNOWN_AGENT_MODELSis the single source of truth the dashboard re-exports, so server and UI can no longer drift;claude-opus-4-8joinsclaude-sonnet-4-6as a legacy id that still renders and edits. assigned_tois validated — a model or provider name such asopusorglmused 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 atimpl:*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_skillsno longer crash withrequire is not defined, and a reset preserves agent departments. - Backups you can trust —
--forcecheckpoints the WAL before renaming and uses SQLite-pairable backup names, so the.bakalone 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/-shmfiles), and--helpfinally 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 thewf:write-commit-messagesskill), andupdate_ticketrefusesqa_verifiedwhile 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_hoursagainst the assigned agent; phase transitions snapshot too. Retros quote real numbers instead of0h. - Leaner internals —
tools.tsanddashboard.tsboth 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 thefabletier.
New in 2.0 — Process 2.0 🚦
- Planning gates that close the retro loop — sprints refuse to start while retro
try_nextlearnings 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 / removedinstead of inflating completion rates. - Terminal cockpit — tools render width-locked progress cards in colored ```diff fences, and the
code-context-statuslinebin 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 TICKETSdiff 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.
License
MIT
VM. studio / vlm · open source · look per vm-brand playbook
Reviews (0)
Sign in to leave a review.
Leave a reviewNo results found