repopedia

中文文档 · Gallery · Agent Skill

Code is a graph — calls, dependencies, inheritance — but today's AI doc tools pretend it's text. repopedia recovers the structure first (AST → knowledge graph), then grows answers, wikis, and impact analysis from the graph. The graph says what's true (every claim cites file:line); the LLM makes it readable.

repopedia is MIT-licensed, local-first, and dependency-light: pip install and index any repo. No Docker, no server, no vendor lock-in.

The diagram above was generated by repopedia itself: repopedia wiki on this repo, rendered from the module-dependency Mermaid it produced. Dogfooding from day one.

Why a graph, not chunks

Naive code understanding chunks source files, embeds them, and retrieves the top-k chunks most similar to a question. That works for "where is the retry logic?" — the answer sits in one chunk. It breaks on structural questions like:

If I change Engine.run, what breaks?

No single chunk contains the answer. You need the call graph: who calls run, who calls them, and so on. Vector similarity can't do graph traversal; a knowledge graph can. repopedia builds that graph with tree-sitter (precise, language-aware parsing — not regexes), then answers from it.

Architecture

flowchart LR
    A[Source repo<br/>.py / .ts / .tsx] --> B[tree-sitter<br/>extractors]
    B --> C[FileFacts<br/>symbols · calls · imports · inherits]
    C --> D[indexer<br/>cross-file resolution]
    D --> E[(SQLite graph<br/>nodes + edges)]
    E --> F[queries<br/>blast radius · incremental]
    E --> G[MCP server<br/>7 tools]
    E --> H[wiki generator<br/>pages + diagrams from graph]

Querying the graph

cd ./myrepo
repopedia query callers pkg.mod.Service.run     # who calls it (file:line)
repopedia query callees pkg.mod.Service.run     # what it calls (unresolved shown as <unresolved: raw>)
repopedia query inherits pkg.mod.Service        # base classes, nearest first
repopedia query file pkg/mod.py                 # symbols defined in a file
repopedia blast-radius pkg.mod.Service.run --depth 3
repopedia search "retry handler"                 # BM25 + one graph hop

blast-radius answers "if I change this, what breaks?": transitive reverse calls traversal up to --depth, plus every file that imports the symbol's file. Each hit cites file:line and how it was reached (calls(2), imports…). Add --json to any command for machine-readable output — the same functions back the Week 3 MCP server.

Python API (all returns are plain JSON-serializable dicts/lists):

from repopedia.store import open_store
from repopedia import query

with open_store("myrepo/.repopedia/graph.db") as s:
    for hit in query.blast_radius(s, "pkg.mod.Service.run", depth=3):
        print(hit["depth"], hit["via"], hit["qualified_name"],
              f"{hit['file']}:{hit['line_start']}")

Incremental updates

repopedia update ./myrepo
# updated: +1 added, ~2 modified, -0 deleted

update diffs against the commit the graph was built from (stored as head_sha in the DB) and re-extracts only changed files, re-resolving their edges against the full store. Files that pointed into a changed file (callers, importers) get their references repaired too. Non-git directories fall back to a full reindex with a warning. One honest limitation: previously unresolvable edges in files that point at nothing changed stay unresolved until a full repopedia index.

MCP server: the graph for AI coding agents

The graph's second consumer is not a human — it's your coding agent. repopedia mcp serves the query API over the Model Context Protocol (stdio), so Cursor, Claude Code, Windsurf, or any MCP client can traverse the codebase structurally instead of guessing from text search.

repopedia mcp --repo ./myrepo
# repopedia MCP server: ./myrepo/.repopedia/graph.db (stdio)

The LLM is optional: only ask_codebase synthesizes prose, and only when REPOPEDIA_LLM_BASE_URL / REPOPEDIA_LLM_API_KEY / REPOPEDIA_LLM_MODEL are set (any OpenAI-compatible endpoint). Every other tool works offline, straight from the graph.

Tool	What it does
find_symbol	symbols by qualified/short name, each citing file:line
get_callers / get_callees	one calls hop, each way (unresolved sites marked)
blast_radius	transitive reverse calls + importing files (depth param)
search_codebase	BM25 + one graph hop, ranked with via: lexical|graph
get_file_symbols	everything a file defines
ask_codebase	retrieval + grounded synthesis; without an LLM it returns the evidence block and says so

Client configuration:

# Claude Code CLI
claude mcp add repopedia -- repopedia mcp --repo /path/to/repo

// Cursor / Windsurf / Claude Desktop — mcpServers
{
  "repopedia": {
    "command": "repopedia",
    "args": ["mcp", "--repo", "/path/to/repo"]
  }
}

Agent skill: teach your coding agent when to reach for the graph

The MCP server is the machine interface. The agent skill is the instruction layer: it teaches Claude Code (or any skill-aware agent) when to use repopedia vs ripgrep vs vector RAG, documents all 7 tools in one page, and states the honest limitations up front — so the agent reaches for graph traversal on structural questions instead of grep-guessing.

# Claude Code: project skill
mkdir -p .claude/skills && cp /path/to/repopedia/SKILL.md .claude/skills/repopedia.md

# or global
cp /path/to/repopedia/SKILL.md ~/.claude/skills/repopedia.md

Skills load into the agent's context, so the file is deliberately tight: a decision table (structure → repopedia, meaning → LLM, exact strings → ripgrep), the 7 tools in one-liners, the CLI, and the limitations. See SKILL.md.

Wiki generator: documentation derived from the graph

repopedia wiki ./myrepo --out docs/
# wiki written to ./myrepo/docs
#   architecture.md
#   index.md
#   modules/auth.md
#   ...

This is the anti-DeepWiki move: instead of an LLM reading text chunks and writing plausible prose, pages are generated from graph edges — module tables from defines, dependency lists from imports, the architecture diagram from the actual import graph, "most-called functions" from real call counts. Every structural claim cites file:line; Mermaid diagrams that exceed the node cap say so on the page.

Before generating, repopedia compares the graph's head_sha against git HEAD. If the graph is stale, it prints a warning and embeds it in index.md — a wiki that might be outdated says so loudly instead of lying quietly. (Run repopedia update first; note that previously unresolved references in unchanged files only heal on a full reindex.)

With an LLM configured (same env vars as above), index.md and module pages get short prose summaries synthesized under a strict cite-only-what-you're-given prompt. Without one, you get a deterministic structural wiki — tables plus diagrams, no prose claims — which is genuinely useful on its own: it answers "what lives where" with citations. Same graph → byte-identical markdown, every time.

Beautiful diagrams: pair with archify

repopedia's diagrams are truthful — every edge comes from the code graph — but raw Mermaid is not beautiful. For presentation-quality output, hand the Mermaid to archify (74k stars, MIT), which turns pasted Mermaid into polished interactive HTML diagrams. The division of labor is clean: repopedia guarantees the graph is true; archify makes it beautiful.

# 1. Generate the wiki (diagrams included)
repopedia wiki ./myrepo --out docs/

# 2. Copy any ```mermaid block from docs/architecture.md

# 3. Paste it into archify → export beautiful interactive HTML

This works because repopedia's Mermaid is derived, not hallucinated: pasting an LLM-invented diagram into a beautifier just gives you a prettier lie.

Search: BM25 + graph, no vectors (deliberate)

Code identifiers are not natural language. "where is retry handled" is answered better by matching the symbol retry / handle_retry and then walking the graph (who calls it, what file it's in) than by embedding the query into a vector space trained on prose. So repopedia search ranks symbols with a hand-rolled BM25 (~40 lines, zero dependencies) over qualified names, file paths, and kinds, then expands one hop along calls / inherits / imports to pull in structurally related symbols — marked "via": "graph" in the output. Structure beats embeddings for "where" questions; vectors may come later as a supplement.

Quickstart

pip install repopedia        # or: pip install -e .  (from source)
repopedia index ./myrepo
# indexed ./myrepo
#   db:      ./myrepo/.repopedia/graph.db
#   files:   132 parsed, 1 skipped
#   symbols: 841
#   edges:   2130

Limit to one language, or choose the DB location:

repopedia index ./myrepo --language py
repopedia index ./myrepo --db /tmp/graph.db

Python API:

from repopedia.store import open_store

with open_store("myrepo/.repopedia/graph.db") as s:
    for sym in s.find_symbol("Engine.run"):
        print(sym["qualified_name"], sym["file"], sym["line_start"])
    for e in s.in_edges(sym["id"], kind="calls"):   # who calls Engine.run?
        print("called by:", e["src_qualified"], e["src_file"])

What gets extracted

Language	Extensions	Symbols	Edges
Python	.py	classes, functions, methods (incl. decorated/async/nested)	defines, imports (abs + relative), calls, inherits
TypeScript	.ts, .tsx	classes, functions, methods (incl. exported)	defines, imports (relative), calls (+ new), inherits (extends)

Skipped, never fatal: node_modules/, .git/, venv/, __pycache__/, dist/, build/, non-UTF8 files, and files with syntax errors (logged as warnings — tree-sitter error recovery is deliberately not trusted for partial extraction).

Graph schema

nodes(id, kind, name, qualified_name, file, line_start, line_end, language)
-- kind: file | class | function | method
-- qualified_name: dotted path, e.g. "pkg.mod.Service.run"
-- file: repo-relative path; line_* are 1-based inclusive

edges(src, dst, kind, data)
-- kind: defines | imports | calls | inherits
-- dst is NULL when the reference can't be resolved in-repo
-- data (JSON) always keeps the raw written form:
--   imports  -> {"module": "pkg.util"}
--   calls    -> {"raw": "helper"} (+ "candidates": N when ambiguous)
--   inherits -> {"raw": "Base"}

Resolution rules (heuristic, documented):

• calls: resolved by short name when unambiguous in the repo. self.x / this.x match method x; ClassName(...) resolves to the class node (constructor call). Ambiguous or unknown names stay dst=NULL with the raw name preserved for later phases to refine.
• imports: resolved via normal module-resolution rules (pkg/util.py, __init__.py, ./util → util.ts(x)/index.ts(x)). Stdlib, third-party, and bare specifiers stay unresolved with the module string recorded.
• inherits: resolved when the base class name is unique in the repo.

The schema is stable: Week 2 (query API, blast-radius = reverse calls traversal, git-diff incremental reindex) and Week 3 (MCP tools, wiki pages + Mermaid diagrams generated from the graph with file:line citations) build on exactly these tables.

Roadmap

• Week 1 ✅: tree-sitter indexer (Python + TypeScript), SQLite store, CLI
• Week 2 ✅: query API (callers/callees, blast radius, inheritance, file symbols), git-diff incremental reindex with reference repair, BM25 + graph hybrid search
• Week 3 ✅: MCP server (7 tools: find_symbol, get_callers/callees, blast_radius, search_codebase, get_file_symbols, ask_codebase with optional grounded LLM synthesis), wiki generator (index + per-module pages + architecture, all derived from the graph with file:line citations, deterministic output, staleness warnings)
• Later: more languages (Go, Java, Rust), vector embeddings as an optional supplement, hosted demo

What repopedia is NOT

• Not a vector RAG clone. No embeddings in MVP — deliberately. Structure first, vectors later as a supplement.
• Not a DeepWiki clone. DeepWiki-style tools generate prose from text chunks; repopedia generates from the graph. Different foundation, different accuracy properties: our wiki pages are only as wrong as the parser, never as wrong as a hallucinating LLM.
• Not an IDE. The graph is built for two consumers: humans reading generated wikis, and AI coding agents querying via MCP.
• Not magic. Unresolved references (dst=NULL) are shown, not hidden. Stale graphs warn loudly. The LLM is instructed to cite only what the graph gave it — and when no LLM is configured, repopedia says so instead of faking synthesis.

License

MIT — use it at work, ship it in products, no strings attached. See LICENSE.