rpg-encoder

Give your AI agent a brain for your codebase.

AI coding agents waste most of their tool calls fumbling through your codebase with grep, cat, find, and file reads. rpg-encoder fixes that. It builds a semantic graph of your code with Tree-sitter — not just what calls what, but what every function does — and gives your AI assistant whole-repo understanding via MCP in a single tool call.

Quick Start

claude mcp add rpg -- npx -y -p rpg-encoder rpg-mcp-server

One command. Works with Claude Code, Cursor, opencode, Windsurf, or any MCP-compatible agent. No Rust toolchain, no cloning, no building — npx downloads a pre-built binary for your platform.

Then open any repo and tell your agent:

"Build and lift the RPG for this repo"

Your agent handles everything: indexes entities (seconds), reads each function and adds intent-level features (a few minutes), organizes them into a semantic hierarchy, and commits .rpg/graph.json for your team.

For repos with ~100+ entities, lifting_status will tell your agent to delegate the lifting loop to a sub-agent or a cheaper model — feature extraction is pattern-matching, not novel reasoning. If your runtime has no sub-agent mechanism, run rpg-encoder lift --provider anthropic|openai from the terminal with an API key — the CLI drives an external LLM directly with no agent involvement. After the CLI finishes, call reload_rpg in your session to load the updated graph. The CLI lifts entities with no features; re-lifting stale entities (features present but outdated after code changes) is handled by the in-session MCP flow, not the CLI.

Once lifted, try:

• "What handles authentication?" — finds code even when nothing is named "auth"
• "Show everything that depends on the database connection"
• "Plan a change to add rate limiting to API endpoints"

Use RPG before grep, cat, find

The server instructions tell your agent to reach for RPG tools FIRST for any question about code structure or behavior. That reflex matters — grep, cat, and ad-hoc file reads burn tokens and miss semantic relationships RPG already knows.

Fall back to grep, cat, or file reads only when the query is about literal text (string search, comments, TODOs, log messages) — not about structure.

How It Works

1. Parse — Tree-sitter extracts entities (functions, classes, methods) and dependency edges (imports, calls, inheritance) from 15 languages.
2. Lift — An LLM (your agent, or a cheap API like Haiku) reads each entity and writes verb-object features: "validate JWT tokens", "serialize config to disk".
3. Organize — Features cluster into a 3-level semantic hierarchy (Area → Category → Subcategory) that emerges from what the code does, not the file tree.
4. Understand — semantic_snapshot compresses the whole graph into ~25K tokens. Your LLM reads it once and knows the repo.

The semantic snapshot

Instead of grepping through files, the LLM calls semantic_snapshot once and receives:

• Hierarchy — every functional area with aggregate features
• Entities — every function, class, method grouped by area, with its semantic features
• Dependency skeleton — condensed call graph with qualified names
• Hot spots — top 10 most-connected entities (the architectural backbone)

~25K tokens covers ~1000 entities. That's 2-3% of a 1M context window — the LLM starts every session already knowing your repo.

Self-maintaining graph

Whenever your working tree changes — committed, staged, or unstaged — the MCP server automatically re-syncs before responding to the next query. A changeset hash over (path, size, mtime) means repeated saves of the same file trigger one sync, and idle queries trigger none. Reverts are detected too: if a previously-dirty file returns to its HEAD state, the graph is restored.

Two ways to lift

auto_lift calls a cheap external LLM directly — your coding subscription never touches the lifting work. Use api_key_env to resolve keys from environment variables so they never appear in tool call transcripts.

Architecture

Seven Rust crates, one MCP server binary, one CLI binary:

MCP Tools (27)