rpg-encoder

[!NOTE] Independent implementation. Built from scratch in Rust by reading the RPG-Encoder paper (Luo et al., 2026, Microsoft Research). No shared code with any other implementation. Not affiliated with or endorsed by Microsoft. All code is original work; the paper is cited for attribution.

Coding agent toolkit for semantic code understanding.

rpg-encoder builds a semantic graph of your codebase. Your coding agent (Claude Code, Cursor, etc.) analyzes the code and adds intent-level features via the MCP interactive protocol. Search by what code does, not what it's named.

[!TIP] New to RPG? See How RPG Compares to understand where it fits alongside Claude Code, Serena, and other tools. For a detailed algorithm-by-algorithm comparison with the research paper, see Paper Fidelity.

Install

The MCP server automatically detects the project root — no path argument needed.

Add to your MCP config (Claude Code ~/.claude.json, Cursor settings, opencode, etc.):

{
  "mcpServers": {
    "rpg": {
      "command": "npx",
      "args": ["-y", "-p", "rpg-encoder", "rpg-mcp-server"]
    }
  }
}

[!TIP] The path argument is optional. When omitted, the server falls back to the current working directory. MCP clients (like opencode, Claude Code, Cursor) launch the server from the workspace directory, so current_dir() automatically points to your project. If you pass a path explicitly, it will use that instead.

git clone https://github.com/userFRM/rpg-encoder.git
cd rpg-encoder && cargo build --release

Then use the binary path directly:

{
  "mcpServers": {
    "rpg": {
      "command": "/path/to/rpg-encoder/target/release/rpg-mcp-server"
    }
  }
}

[!TIP] The binary also accepts an optional path argument. Omit it to use the current working directory.

The path argument is optional — the server defaults to the current working directory. This works automatically because MCP clients launch the server from the workspace directory.

Global config (all repos use cwd)

No path needed — each session uses the directory where the MCP client was started:

{
  "mcpServers": {
    "rpg": {
      "command": "npx",
      "args": ["-y", "-p", "rpg-encoder", "rpg-mcp-server"]
    }
  }
}

Per-project override (explicit path)

If you need a specific repo, pass the path:

{
  "mcpServers": {
    "rpg": {
      "command": "npx",
      "args": ["-y", "-p", "rpg-encoder", "rpg-mcp-server", "/path/to/this/repo"]
    }
  }
}

The project-level config overrides the global one. Restart Claude Code after creating/modifying configs.

Lifecycle

graph LR
    A[Install] --> B[Build]
    B --> C[Lift]
    C --> D[Use]
    D --> E[Update]
    E --> C

You install it. Your agent does the rest.

Getting Started

Tell your coding agent:

"Build and lift the RPG for this repo"

That's it. The agent handles everything. Here's what happens:

1. Build — Indexes all code entities and dependencies (~5 seconds)
2. Lift — Agent analyzes each function/class and adds semantic features (~2 min per 100 entities)
3. Organize — Agent discovers functional domains and builds a semantic hierarchy (~30 seconds)
4. Save — Graph is written to .rpg/graph.json — commit it so everyone benefits

Once lifted, try queries like:

• "What handles authentication?"
• "Show me everything that depends on the database connection"
• "Plan a change to add rate limiting to API endpoints"

The RPG (Repository Planning Graph) is a hierarchical, dual-view representation from the research papers cited below:

1. Parse — Extract entities (functions, classes, methods) and dependency edges (imports, invocations, inheritance) using tree-sitter. Build a file-path hierarchy.
2. Lift — Your coding agent analyzes entity source code and adds verb-object semantic features (e.g., "validate user credentials", "serialize config to disk") via the MCP interactive protocol (get_entities_for_lifting → submit_lift_results).
3. Hierarchy — Your agent discovers functional domains and assigns entities to a 3-level semantic hierarchy (build_semantic_hierarchy → submit_hierarchy).
4. Ground — Anchor hierarchy nodes to directories via LCA algorithm, resolve cross-file dependency edges.

The graph is saved to .rpg/graph.json and should be committed to your repo — this way all collaborators and AI tools get instant semantic search without rebuilding.

MCP Tools

Build & Maintain

Semantic Lifting

Navigate & Search

Plan & Analyze

Lifting: What It Is

Lifting is the process where your coding agent reads each function, class, and method in your codebase and describes what it does in plain English — verb-object features like "validate user credentials" or "serialize config to disk". These features power semantic search: find code by what it does, not what it's named.

• No API keys needed — your connected coding agent (Claude Code, Cursor, etc.) is the LLM
• One-time cost — lift once, commit .rpg/, and every future session starts instantly
• Resumable — if interrupted, lifting_status picks up exactly where you left off
• Incremental — after code changes, update_rpg detects what moved and only re-lifts those entities
• Scoped — lift the whole repo or just a subdirectory ("src/auth/**")

1. Ask your agent to "lift the code" (or call get_entities_for_lifting with a scope)
2. The tool returns entity source code with analysis instructions
3. Your agent analyzes the code and calls submit_lift_results with semantic features
4. The agent continues through all batches automatically, dispatching subagents for large repos
5. After lifting, finalize_lifting → build_semantic_hierarchy → submit_hierarchy

Supported Languages

The CLI provides structural operations (no semantic lifting — use the MCP server for that).

# Install
npm install -g rpg-encoder

# Build a graph
rpg-encoder build
rpg-encoder build --include "src/**/*.py" --exclude "tests/**"

# Query
rpg-encoder search "parse entities from source code"
rpg-encoder fetch "src/parser.rs:extract_entities"
rpg-encoder explore "src/parser.rs:extract_entities" --direction both --depth 2
rpg-encoder info

# Incremental update
rpg-encoder update
rpg-encoder update --since abc1234

# Paper-style reconstruction schedule (topological + coherent batches)
rpg-encoder reconstruct-plan --max-batch-size 8 --format text
rpg-encoder reconstruct-plan --format json

# Pre-commit hook (auto-updates graph on every commit)
rpg-encoder hook install

Create .rpg/config.toml in your project root (all fields optional):

[encoding]
batch_size = 50             # Entities per lifting batch
max_batch_tokens = 8000     # Token budget per batch
drift_threshold = 0.5       # Jaccard distance midpoint reference
drift_ignore_threshold = 0.3  # Below: minor edit, in-place update
drift_auto_threshold = 0.7    # Above: auto-queue for re-routing

[navigation]
search_result_limit = 10

rpg-encoder/
├── rpg-core        Core graph types (RPGraph, Entity, HierarchyNode), storage, LCA
├── rpg-parser      Tree-sitter entity + dependency extraction (15 languages)
├── rpg-encoder     Encoding pipeline, semantic lifting utilities, incremental evolution
│   └── prompts/        Prompt templates (embedded via include_str!)
├── rpg-nav         Search, fetch, explore, TOON serialization
├── rpg-cli         CLI binary (rpg-encoder)
└── rpg-mcp         MCP server binary (rpg-mcp-server)

Do I need an API key or a local LLM?

No. Your connected coding agent (Claude Code, Cursor, etc.) is the LLM. rpg-encoder sends source code to the agent via MCP tools, the agent analyzes it and sends back semantic features. No API keys, no external services, no local model downloads.

How long does lifting take?

Roughly 2 minutes per 100 entities. A small project (50 files, ~200 entities) takes about 5 minutes. A large project (500+ files) should use parallel subagents — your agent handles this automatically. Build and hierarchy steps are near-instant.

What happens when I delete or rename files?

Run update_rpg (or use the pre-commit hook). It diffs against the last indexed commit, removes deleted entities, re-extracts renamed/modified files, and marks changed entities for re-lifting. The graph stays consistent without a full rebuild.

Can I lift only part of the codebase?

Yes. Pass a file glob to get_entities_for_lifting: "src/auth/**", "crates/rpg-core/**", etc. You can also use .rpgignore (gitignore syntax) to permanently exclude files like vendored dependencies or generated code.

What if lifting gets interrupted?

The graph is saved to disk after every submit_lift_results call. Start a new session, call lifting_status, and it picks up exactly where you left off — only unlifted entities are returned.

How does semantic search work?

search_node uses hybrid scoring: BGE-small-en-v1.5 embeddings for semantic similarity plus lexical matching for exact names and paths. Query with intent ("handle authentication") or exact identifiers ("AuthService::validate") — both work.

Should I commit .rpg/ to the repo?

Yes. The .rpg/graph.json file contains the full semantic graph. Committing it means collaborators and CI agents get instant semantic search without re-lifting. The graph is deterministic (sorted maps, stable serialization), so diffs are meaningful.

What about monorepos or very large codebases?

Use scoped lifting to process one area at a time ("packages/api/**", "services/auth/**"). Your coding agent will automatically dispatch parallel subagents for large scopes. The incremental update system (update_rpg) keeps the graph current without full rebuilds. For very large repos, use .rpgignore to exclude vendored code, generated files, and test fixtures.

References

This project is based on the following research papers. All credit for the theoretical framework, algorithms, and evaluation methodology belongs to the original authors.

• RPG-Encoder: Luo, J., Yin, C., Zhang, X., et al. "Closing the Loop: Universal Repository Representation with RPG-Encoder." arXiv:2602.02084, 2026. [Paper] [Project Page] [Official Code]

• RPG (ZeroRepo): Luo, J., Yin, C., et al. "RepoGraph: Enhancing AI Software Engineering with Repository-level Code Graph." arXiv:2509.16198, 2025. [Paper]

• TOON: Token-Oriented Object Notation — an LLM-optimized data format used for MCP tool output and LLM response parsing. [Spec]

License

Licensed under the MIT License.

This is an independent implementation. The RPG-Encoder paper and its associated intellectual property belong to Microsoft Research and the paper's authors. This project implements the publicly described algorithms and does not contain any code from Microsoft.