context-rider

A compact map of your codebase plus a memory that survives context clears, for AI coding assistants (Claude Code, Antigravity, and other MCP clients). Instead of re-reading files and re-explaining decisions every session, your assistant asks for a small sub-graph or a short "where were we" summary.

Everything runs locally. No network calls, no LLM calls — code is parsed with Tree-sitter and stored in a SQLite file inside your project.

Use it in any project

Needs Node 18+ (20 recommended). From inside the project:

npx context-rider-mcp init

Then restart your assistant (approve the new server if it asks) and check:

npx context-rider-mcp status      # should say LIVE

That's the whole setup. init detects your assistant (Claude Code by default; --client antigravity|all to choose), writes its project config, adds a few lines to CLAUDE.md telling the assistant when to use the tools, and git-ignores its data folder (.context-rider/).

Is it working?

| Check | What you see | |---|---| | npx context-rider-mcp status | LIVE / STALE / NOT RUNNING, files indexed, tool calls, estimated token savings, other servers on the project. Exit code 0 only when live. | | Ask your assistant to call get_status | The same report from inside the session — proves the assistant is really connected. | | npx context-rider-mcp doctor | Diagnoses a broken setup: Node version, native SQLite module, parsers, project, config, instructions, server. Every failure comes with a fix. Start here if something's off. |

The server only runs while your assistant has the project open, so NOT RUNNING with the assistant closed is normal.

Sharing with your team

With the published package, init writes a portable .mcp.json (npx -y context-rider-mcp@<version> serve — no paths from your machine). Commit .mcp.json and CLAUDE.md; teammates only need Node 18+, and the tool downloads itself on first use. Each person's index and saved tasks stay in their own git-ignored .context-rider/.

What your assistant gets

| Tool | Use | |---|---| | reload_lean_context | Start of a session: directives, the 15 most recent open tasks, a "last commit N days ago, M files changed since" line, and the code around the files those tasks touched | | read_subgraph | Before opening files: imports, symbols and call chains (depth 2 reaches call edges) | | commit_epoch_state | Before clearing/compacting: save summary, tasks and touched files | | get_status | Is it live and working? |

Nothing can force an assistant to call these, and nothing fires automatically on /clear. The CLAUDE.md block asks it to; for other clients run npx context-rider-mcp rules and paste the output into that client's instructions. If it matters, tell the assistant to commit before you clear.

What it costs and saves

• Fixed cost per session: ~470 tokens (four tool definitions ~360 + the instructions block ~110).
• Savings: status shows, for read_subgraph, tokens returned vs the raw size of the files it covered. These are estimates (4 characters ≈ 1 token) that assume those files would otherwise be read in full. It pays off on real files; on tiny or symbol-dense ones it can save little or cost extra, and status says so.

Restarting after days away

Saved tasks and decisions persist in .context-rider/graph.db. On every start the server re-scans the project (no LLM tokens) and drops entries for files you deleted or renamed while it was off. If several assistants/sessions use the same project, each gets its own server, they share one database, and later ones skip the rescan.

Undo

npx context-rider-mcp remove           # removes only what init added; keeps saved data
npx context-rider-mcp remove --purge   # also deletes .context-rider/

Other servers in your .mcp.json and the rest of your CLAUDE.md are left untouched.

Limits

• Languages: TypeScript, JavaScript (incl. JSX/TSX), Python.
• Tested on macOS with Node 20. Linux should work; Windows is untested (Claude Code on native Windows may need the npx command wrapped as cmd /c npx).
• Config formats for Claude Code (.mcp.json) and Antigravity (.agents/mcp_config.json) follow their docs but were verified with a real MCP client, not the apps themselves.

For the maintainer: publishing and sharing the tool

npm run build && npm test
npm pack                 # -> context-rider-mcp-<version>.tgz, ~46 kB; send it to someone, or:
npm publish              # then everyone can use `npx context-rider-mcp init`
npm i -g github:<you>/<repo>   # alternative: install straight from git

Until it's published, run from a checkout: npm install && npm run build, then node dist/cli.js init inside the target project (this writes a machine-specific config — don't commit it — or pass --portable once published). Licensed MIT.

Development

npm test          # vitest
npx tsc --noEmit

Design: ARCHITECTURE.md · plan: ROADMAP.md · rationale: DECISIONS.md · current state: STATE.md