Rig

Watch your codebase become a constellation — and give your AI agent a map of it.

▶ Watch the full demo with audio

Rig builds a local-first semantic knowledge graph of your project, renders it as an interactive map you can fly through, and exposes it to coding agents (Claude Code, Cursor, Codex, opencode) over MCP. Agents navigate by structure and by meaning, and they keep what earlier sessions decided, attached to the code it is about.

Everything runs on your machine. No API key, no upload, nothing leaves your laptop.

Quickstart

In any project directory:

npx rig-constellation

(Have Bun? bunx rig-constellation works too.) That's the whole thing. One command:

  ⬡ Rig — mapping my-project
  http://localhost:7491

  ✓ initialized  ./.rig
  ✓ map live    http://localhost:7491
  → 1/6 extract      ██████████████████ 212/212
  → 5/6 hubness      ████████████████░░
  ✓ indexed     1,204 nodes · 3,891 edges · 212 files · 36 skills
  ✓ wired Claude Code  project
      wrote     .mcp.json
      wrote     .claude/settings.json
      wrote     CLAUDE.md

  press Ctrl-C to stop the map.

It initializes .rig/, opens the live map first, then indexes your code so the graph assembles in the already-open browser tab in real time, and wires whichever agent it detects into this project, listing every file it writes. The map title and port are derived per project, so two checkouts can run side by side on stable, distinct ports. Re-run any time, or use the explicit subcommands below.

The command is rig (alias: rig-constellation). Prefer a global install? npm i -g rig-constellation (or bun install -g rig-constellation), then rig start. Installed locally with npm i rig-constellation? The binary lives in node_modules/.bin — run it with npx rig start (or install with -g to get rig on your PATH).

What it can do

Map and navigate code

• A live map of your codebase. Files, symbols, calls, imports, tests and dependencies as a graph you can fly through in the browser. The map updates live while agents work.

• Structural questions in one call. Callers, callees, impact ("what breaks if I change X"), critical paths, neighbours and hubs, instead of grep-and-read.

• Search in plain language. "Where do we refresh expired sessions?" finds the code. Exact names, keywords (including identifier words, so "handle login" matches handleLogin) and on-device embeddings are fused into one ranking. A symbol name still returns that symbol first.

• Orientation on demand. rig_overview (also the MCP resource rig://overview, and rig overview on the command line) returns a compact markdown map of the repository, about 2,000 tokens long. It covers:

  • packages and their purposes
  • entry points
  • the most-referenced symbols with file:line
  • route and handler tables
  • where the tests live
  • recent decisions

  The map is cached and refreshed on every index, sync and file change.

• Magnetic pull. "What's related to X", ranked by graph distance, semantic similarity and recent activity, with the score components broken out.

• Dependency intelligence. Installed versions, declared-but-unused packages, imports with no declaration, and version conflicts across a monorepo. It covers npm and Python: PyPI names are matched to their import names (PyYAML → yaml), and the standard library is never flagged.

Remember across sessions and agents

• Memory that survives re-indexing. Index, sync, file edits and line moves keep everything agents attach to code:

  • waypoints (decisions, constraints, open questions)
  • aliases, annotations and promotions
  • proposed and accepted links

  If a symbol disappears, its memory is set aside rather than lost, and re-attached when the symbol comes back.

• Waypoints live outside the context window. They are searchable by meaning (rig_waypoints query="…"), and the next session can load the previous one's.

• Human review where it matters. Links an agent proposes wait for your accept or reject on the map, and every change can be undone step by step.

• Portable memory. rig export-memory and rig import-memory carry agent memory across fresh clones and machines.

• One graph, many agents. Claude Code, Cursor, Codex and opencode can all work on the same project at the same time. Writes are concurrency-safe and record which agent made them.

Fit into your setup

• Wiring goes into the current project by default (rig install claude), and rig uninstall removes exactly what was added. Each agent gets rig's approval policy in its own permission format; risky writes ask first.
• A live graph. A single file watcher per project keeps the graph current while you code.
• Languages: TypeScript, TSX, JavaScript, JSX, Python and Markdown, plus package.json, pyproject.toml, requirements*.txt and their lockfiles.

Measured, not claimed

scripts/bench runs real agents (Claude Haiku 5.5 via OpenRouter) on 16 questions about next-auth at a pinned commit, and checks every answer automatically. With grep and rig available, as in a real agent session:

• Natural-language questions cost fewer tokens than with grep alone.
• Exact identifier lookups still cost more. The installed guide tells agents to use grep for those.
• Injecting the orientation map into every prompt cost more than it saved. That's why it's on demand.

The raw results and reports are in scripts/bench/results/.

What your agent does differently

Without a map, an agent answers "what breaks if I change parseConfig?" by grepping the string and reading whatever files match — blind, lossy, and token-expensive.

With Rig it's one call:

rig_impact parseConfig
→ 7 transitive callers, ranked:
   loadSettings          calls · depth 1
   bootstrap             calls · depth 2
   __tests__/config…     tests · depth 1
   …

And "what else should I look at?" isn't a guess — rig_pull returns related anchors scored by graph distance, on-device embedding similarity, and recent activity, with the three components broken out so the ranking is explainable, not a black box:

rig_pull parseConfig
→ { node: "validateSchema", score: 0.81,
    components: { structural: 0.4, semantic: 0.9, recency: 0.7 } }

That ranked, self-explaining retrieval — not a flat grep dump — is the difference.

Privacy & local-first

• Embeddings run locally via a small on-device model (bge-small). No API key required.
• The graph lives in .rig/rig.db in your project. rig auto-adds .rig/ to your .gitignore.
• Nothing is uploaded. The map UI is served on loopback only and needs its per-project session token, with Host and Origin checks against other web pages; rig start opens it signed in.

Wiring your agent

bunx rig-constellation auto-detects the agents you have installed and wires them into the current project — it never edits your user-level config. To wire one explicitly:

rig install claude            # also: cursor · codex · opencode
rig install claude --global   # your user-level config instead: applies to every project
rig uninstall claude          # remove exactly what install added (--all · --global · --dry-run)

Each install merges Rig's MCP server entry, Rig's per-tool approval policy (in the agent's own permission format), and a short usage guide between <!-- rig:begin --> markers, leaving the rest of each file alone — re-running it is safe. The agent spawns rig serve --mcp on demand; Claude Code asks you once to approve a server from a project's .mcp.json. In a directory without .rig/, the server still starts and every tool answers with how to fix it (rig init or rig start).

OpenRouter is an API, not an MCP host: rig install openrouter only writes a reference config to copy into the MCP client you use with it.

Commands

Run rig --help for the full list.

How it works

.contracts/ is the declarative source of truth (tools, anchors, migrations, events); bun run gen emits the matching code into generated/. The graph is plain SQLite. Search fuses exact names, SQLite FTS5 keyword matches and on-device embedding similarity by reciprocal rank; "what's related" is a single magnetic-pull scoring function over structural edges, on-device embeddings, and recency. The map UI is a force-graph over WebSocket.

• packages/core — the Rig class: DB, extraction, graph, embeddings, magnetic pull
• packages/mcp — MCP stdio server + tool dispatch
• packages/web — Fastify + WebSocket + React map UI
• packages/cli — the rig binary
• packages/contracts — defineToolContract & friends

See docs/contracts.md to add a tool, docs/integration.md for the architecture, and COMPATIBILITY.md for the stability promise.

Requirements

• Bun ≥ 1.1 (primary), or Node ≥ 22 (fallback).
• Works on macOS, Linux, and Windows.

Contributing

Adding a tool means touching one file in .contracts/ and one implementation — the generator wires the rest. Start with docs/contracts.md, then docs/integration.md for where new ideas plug in. Stable tools are protected by a compatibility gate (bun run check:compat); see COMPATIBILITY.md.

License

Apache-2.0. Rig's extraction layer is derived from CodeGraph (MIT, © Colby Mchenry); those portions remain under their original MIT terms — see LICENSE-CODEGRAPH.txt and NOTICE. With thanks.