{ "markdown": "

rpg-encoder

\n\n

\n Give your AI agent a brain for your codebase.\n

\n\n

\n \"CI\"\n \"MIT\n \"Rust\n \"npm\"\n \"MCP\"\n \"Stars\"\n

\n\n
\n\nAI 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](https://tree-sitter.github.io/tree-sitter/) — not just *what calls what*, but *what every function does* — and gives your AI assistant whole-repo understanding via [MCP](https://modelcontextprotocol.io/) in a single tool call.\n\n

\n \"Without\n

\n\n---\n\n## Quick Start\n\n```bash\nclaude mcp add rpg -- npx -y -p rpg-encoder rpg-mcp-server\n```\n\nOne 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.\n\nThen open any repo and tell your agent:\n\n> *\"Build and lift the RPG for this repo\"*\n\nYour 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.\n\nFor 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.\n\nOnce lifted, try:\n\n- *\"What handles authentication?\"* — finds code even when nothing is named \"auth\"\n- *\"Show everything that depends on the database connection\"*\n- *\"Plan a change to add rate limiting to API endpoints\"*\n\n---\n\n## Use RPG before `grep`, `cat`, `find`\n\nThe server instructions tell your agent to reach for RPG tools FIRST for any\nquestion about code structure or behavior. That reflex matters — `grep`, `cat`,\nand ad-hoc file reads burn tokens and miss semantic relationships RPG already\nknows.\n\n| If you'd otherwise reach for... | Use this instead |\n|---|---|\n| `grep -r` / `rg` (by intent) | `search_node(query=\"...\")` |\n| `grep -r` / `rg` (by name) | `search_node(query=\"...\", mode=\"snippets\")` |\n| `cat` / reading a function | `fetch_node(entity_id=\"file:name\")` |\n| chained greps for callers/callees | `explore_rpg(entity_id=\"...\", direction=\"...\")` |\n| recursive grep for \"what depends on X\" | `impact_radius(entity_id=\"...\")` |\n| `wc -l` / `find` / `tree` | `rpg_info` |\n| reading many files for context | `semantic_snapshot` |\n| manual search → fetch → explore chains | `context_pack(query=\"...\")` |\n| \"how do I refactor X safely\" | `plan_change(goal=\"...\")` |\n\nFall back to `grep`, `cat`, or file reads only when the query is about literal text\n(string search, comments, TODOs, log messages) — not about structure.\n\n---\n\n## How It Works\n\n

\n \"Four-stage\n

\n\n1. **Parse** — Tree-sitter extracts entities (functions, classes, methods) and dependency edges (imports, calls, inheritance) from 15 languages.\n2. **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\"*.\n3. **Organize** — Features cluster into a 3-level semantic hierarchy (Area → Category → Subcategory) that emerges from *what the code does*, not the file tree.\n4. **Understand** — `semantic_snapshot` compresses the whole graph into ~25K tokens. Your LLM reads it once and *knows the repo*.\n\n### The semantic snapshot\n\n

\n \"The\n

\n\nInstead of grepping through files, the LLM calls `semantic_snapshot` once and receives:\n\n- **Hierarchy** — every functional area with aggregate features\n- **Entities** — every function, class, method grouped by area, with its semantic features\n- **Dependency skeleton** — condensed call graph with qualified names\n- **Hot spots** — top 10 most-connected entities (the architectural backbone)\n\n~25K tokens covers ~1000 entities. That's 2-3% of a 1M context window — the LLM starts every session already knowing your repo.\n\n### Self-maintaining graph\n\n

\n \"Git\n

\n\nWhenever 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.\n\n### Two ways to lift\n\n| Mode | Command | Cost | Who pays |\n|------|---------|------|----------|\n| **Agent lifting** | *\"Build and lift the RPG\"* | Subscription tokens | Your Claude Code / Cursor subscription |\n| **Autonomous lifting** | `auto_lift(provider=\"anthropic\", api_key_env=\"ANTHROPIC_API_KEY\")` | ~$0.02 per 100 entities | External API key (Haiku, GPT-4o-mini, OpenRouter, Gemini) |\n\n`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.\n\n---\n\n## Architecture\n\n

\n \"Your\n

\n\nSeven Rust crates, one MCP server binary, one CLI binary:\n\n| Crate | Role |\n|-------|------|\n| `rpg-core` | Graph types (RPGraph, Entity, HierarchyNode), storage, LCA algorithm |\n| `rpg-parser` | Tree-sitter entity + dependency extraction (15 languages) |\n| `rpg-encoder` | Encoding pipeline, lifting utilities, incremental evolution |\n| `rpg-nav` | Search, fetch, explore, snapshot, TOON serialization |\n| `rpg-lift` | Autonomous LLM lifting (Anthropic, OpenAI, OpenRouter, Gemini) |\n| `rpg-cli` | CLI binary (`rpg-encoder`) |\n| `rpg-mcp` | MCP server binary (`rpg-mcp-server`) with 27 tools |\n\n---\n\n## MCP Tools (27)\n\n
\nBuild & Maintain (4 tools)\n\n| Tool | Description |\n|------|-------------|\n| `build_rpg` | Index the codebase (run once, instant) |\n| `update_rpg` | Incremental update from git changes |\n| `reload_rpg` | Reload graph from disk after external changes |\n| `rpg_info` | Graph statistics, hierarchy overview, per-area lifting coverage |\n\n
\n\n
\nNavigate & Search (5 tools)\n\n| Tool | Description |\n|------|-------------|\n| `semantic_snapshot` | Whole-repo semantic understanding in one call (~25K tokens for 1000 entities) |\n| `search_node` | Search entities by intent or keywords (hybrid embedding + lexical scoring) |\n| `fetch_node` | Get entity metadata, source code, dependencies, and hierarchy context |\n| `explore_rpg` | Traverse dependency graph (upstream, downstream, or both) |\n| `context_pack` | Single-call search + fetch + explore with token budget |\n\n
\n\n
\nPlan & Analyze (7 tools)\n\n| Tool | Description |\n|------|-------------|\n| `impact_radius` | BFS reachability analysis — \"what depends on X?\" |\n| `plan_change` | Change planning — find relevant entities, modification order, blast radius |\n| `find_paths` | K-shortest dependency paths between two entities |\n| `slice_between` | Extract minimal connecting subgraph between entities |\n| `analyze_health` | Code health: coupling, instability, god objects, clone detection |\n| `detect_cycles` | Find circular dependencies and architectural cycles |\n| `reconstruct_plan` | Dependency-safe reconstruction execution plan |\n\n
\n\n
\nSemantic Lifting (11 tools)\n\n| Tool | Description |\n|------|-------------|\n| `auto_lift` | One-call autonomous lifting via cheap LLM API (Haiku, GPT-4o-mini, OpenRouter, Gemini) |\n| `lifting_status` | Dashboard — coverage, per-area progress, NEXT STEP |\n| `get_entities_for_lifting` | Get entity source code for your agent to analyze |\n| `submit_lift_results` | Submit the agent's semantic features back to the graph |\n| `finalize_lifting` | Aggregate file-level features, rebuild hierarchy metadata |\n| `get_files_for_synthesis` | Get file-level entity features for holistic synthesis |\n| `submit_file_syntheses` | Submit holistic file-level summaries |\n| `build_semantic_hierarchy` | Get domain discovery + hierarchy assignment prompts |\n| `submit_hierarchy` | Apply hierarchy assignments to the graph |\n| `get_routing_candidates` | Get entities needing semantic routing (drifted or newly lifted) |\n| `submit_routing_decisions` | Submit routing decisions (hierarchy path or \"keep\") |\n\n
\n\n---\n\n## Supported Languages\n\n15 languages via Tree-sitter:\n\n| Language | Entity Extraction | Dependency Resolution |\n|----------|------------------|----------------------|\n| Python | Functions, classes, methods | imports, calls, inheritance |\n| Rust | Functions, structs, traits, impl methods | use, calls, trait impls |\n| TypeScript | Functions, classes, methods, interfaces | imports, calls, inheritance |\n| JavaScript | Functions, classes, methods | imports, calls, inheritance |\n| Go | Functions, structs, methods, interfaces | imports, calls |\n| Java | Classes, methods, interfaces | imports, calls, inheritance |\n| C / C++ | Functions, classes, methods, structs | includes, calls, inheritance |\n| C# | Classes, methods, interfaces | using, calls, inheritance |\n| PHP | Functions, classes, methods | use, calls, inheritance |\n| Ruby | Classes, methods, modules | require, calls, inheritance |\n| Kotlin | Functions, classes, methods | imports, calls, inheritance |\n| Swift | Functions, classes, structs, protocols | imports, calls, inheritance |\n| Scala | Functions, classes, objects, traits | imports, calls, inheritance |\n| Bash | Functions | source, calls |\n\n---\n\n## Install\n\n### MCP server (recommended)\n\n```bash\n# Claude Code\nclaude mcp add rpg -- npx -y -p rpg-encoder rpg-mcp-server\n\n# Cursor — add to ~/.cursor/mcp.json\n{\n \"mcpServers\": {\n \"rpg\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"-p\", \"rpg-encoder\", \"rpg-mcp-server\"]\n }\n }\n}\n```\n\nThe server auto-detects the project root from the current working directory — no path argument needed.\n\n
\nCLI\n\n```bash\nnpm install -g rpg-encoder\n\n# Build a graph\nrpg-encoder build\n\n# Query\nrpg-encoder search \"parse entities from source code\"\nrpg-encoder fetch \"src/parser.rs:extract_entities\"\nrpg-encoder explore \"src/parser.rs:extract_entities\" --direction both --depth 2\nrpg-encoder info\n\n# Autonomous lifting via API\nrpg-encoder lift --provider anthropic --dry-run # estimate cost\nrpg-encoder lift --provider anthropic # lift with Haiku (~$0.02/100 entities)\n\n# Incremental update\nrpg-encoder update\n\n# Pre-commit hook (auto-updates graph on commit)\nrpg-encoder hook install\n```\n\n
\n\n
\nBuild from source\n\n```bash\ngit clone https://github.com/userFRM/rpg-encoder.git\ncd rpg-encoder && cargo build --release\n```\n\nThen point your MCP config at `target/release/rpg-mcp-server`.\n\n
\n\n---\n\n## Documentation\n\n- [How RPG Compares](docs/comparison.md) — honest comparison with GitNexus, Serena, Repomix, and others\n- [Paper Fidelity](docs/paper_fidelity.md) — algorithm-by-algorithm comparison with the research paper\n- [Use Cases](use_cases.md) — practical examples of what RPG enables\n- [CHANGELOG](CHANGELOG.md) — release history\n\n---\n\n## Inspirations & References\n\nrpg-encoder is built on the theoretical framework from the RPG-Encoder research paper, with original extensions inspired by tools across the code intelligence landscape:\n\n- **[RPG-Encoder paper](https://arxiv.org/abs/2602.02084)** (Luo et al., 2026, Microsoft Research) — semantic lifting model, 3-level hierarchy construction, incremental evolution algorithms, formal graph model `G = (V_H ∪ V_L, E_dep ∪ E_feature)`.\n- **[GitNexus](https://github.com/abhigyanpatwari/GitNexus)** — precomputed relational intelligence, blast radius analysis, Claude Code hooks. Showed that a code graph tool must be invisible to be essential.\n- **[Serena](https://github.com/oraios/serena)** — symbol-level precision via LSP. Demonstrated that real-time code awareness matters more than batch analysis.\n- **[TOON](https://github.com/toon-format/toon)** — Token-Oriented Object Notation for LLM-optimized output.\n\nThis is an independent implementation. All code is original work under the MIT license. Not affiliated with or endorsed by Microsoft.\n\n---\n\n## License\n\n[MIT](LICENSE)\n", "bytes": 14628, "sha": "83b4c2a73639c27f784dffb54ee763cec23d897c8971513ae068f118a29b3ec7", "repo_slug": "userfrm/rpg-encoder", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_userfrm_rpg_encoder_5beaac2d/readme" }