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, …) over MCP. Your agent stops grepping blindly and starts navigating — by structure, by meaning, and by what it's touched before.

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 you get

• A map of your codebase. Files, symbols, calls, imports, and dependencies as a navigable graph — not a file tree.
• Magnetic pull. Ask "what's related to X" and get a ranked answer that blends graph distance, semantic similarity, and what's been active recently.
• Hubs. The structurally important anchors surface first, so a 5k-node graph stays legible.
• Dependency intelligence. "What version of X do I have?" and "what's declared but never imported?" become one-hop graph queries.
• Waypoints. Your agent drops durable markers at decisions and constraints. They live in the graph, outside the context window, and stay attached to the code they reference when you re-index. The installed instructions tell each new session to load the previous session's waypoints, and rig export-memory backs them up.
• An MCP tool surface your agent calls directly: search, pull, callers/callees, impact, hubs, deps, and more.

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.

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. Retrieval 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 ≥ 20 (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.