Turn a public Python GitHub repository into a structured onboarding guide: architecture overview, entry points, a read-first path, ranked key files, core abstractions, key execution flows, and suggested first contributions. Once the guide is built you can ask the codebase questions; answers are grounded in excerpts of the real source files, not just the guide, and support follow-up turns.
A hybrid pipeline. A deterministic static layer (tree-sitter) builds a structural map of
the repo, then a bounded LLM agent (20 steps and 60,000 tokens by default) explores that
map to write the guide. Stages communicate only through typed Pydantic contracts:
Manifest → CodeMap → RankedShortlist → Understanding → Guide.
The read-first ranking is fully deterministic, no LLM involved: import in-degree and out-degree, graph proximity to entry points, public API re-export, symbol density, docstring ratio and source size, each normalized to [0, 1].
| Dir | What |
|---|---|
backend/ |
The pipeline, language adapters, LLM client, and the FastAPI web app (repoco.web). |
frontend/ |
Vite + React + TypeScript SPA, a pure client over the web API. |
eval/ |
Evaluation harness: structural metrics plus Claude-as-judge over a frozen benchmark. |
docs/ |
Design spec and implementation plans. |
You need an OpenAI-compatible LLM gateway key (the default gateway is OpenRouter). Set it on the process that runs the backend.
# 1. Backend API (from backend/)
cd backend
OPENROUTER_API_KEY=sk-or-... \
uv run --extra serve uvicorn repoco.web.app:build_app --factory --port 8078
# 2. Frontend (separate terminal)
cd frontend
npm install
npm run dev # http://localhost:5173, proxies the APIOpen http://localhost:5173, paste a github.com/owner/repo URL, and watch the guide
build stage by stage: fetching, analyzing, ranking, exploring, assembling.
No credits? The default models (
qwen/qwen3-coder,meta-llama/llama-3.3-70b-instruct) are paid routes. For a $0 run, point at free models:REPOCO_SMART_MODEL='nvidia/nemotron-3-super-120b-a12b:free' REPOCO_FAST_MODEL='nvidia/nemotron-nano-9b-v2:free'. If no key is set, the server logs a warning at startup and the SPA shows a notice; a failed job returns an actionable message (check key, credits, model).
cd backend
uv run repoco rank /path/to/local/repo # ranked read-first file list
uv run repoco guide /path/to/local/repo # full guide (needs a key)
uv run repoco guide /path/to/local/repo --no-llm # structural guide, no key needed| Var | Default | Purpose |
|---|---|---|
OPENROUTER_API_KEY |
(unset) | LLM gateway key (runtime). Required for LLM guides. |
REPOCO_SMART_MODEL / REPOCO_FAST_MODEL |
qwen3-coder / llama-3.3-70b | Model per tier. |
REPOCO_LLM_BASE_URL / REPOCO_LLM_KEY_ENV |
OpenRouter | Point at any OpenAI-compatible gateway. |
REPOCO_DB_PATH / REPOCO_CACHE_DIR |
repoco.sqlite / .cache/repos |
Web app job DB (jobs and access-key wallets) plus fetched-repo cache. Use an absolute path on a persistent volume in production; the two should be on separate volumes (the server warns otherwise). |
REPOCO_MAX_CACHE_BYTES |
5368709120 (5 GiB) |
LRU cap on the retained repo cache, so it cannot fill the disk. |
GITHUB_TOKEN |
(unset) | Raises the GitHub API limit for repo resolution from 60 to 5,000 requests/hour. Optional but strongly recommended when serving others. |
REPOCO_ENABLE_DOCS |
unset (off) | Set to 1 to expose /docs and /openapi.json. Local dev only, never in production. |
REPOCO_SPA_DIR |
unset | Directory of the built SPA to serve same-origin (set in the container image); unset means API-only. |
ANTHROPIC_API_KEY |
(unset) | The eval judge (Claude), not the runtime. |
Guide prose is LLM output, so it is scored, never asserted. Two layers in eval/:
- Structural metrics, deterministic and CI-gateable: precision and recall of entry points, key-file recall, abstraction recall, and a grounding rate, the fraction of cited file paths that actually exist in the repo.
- Claude-as-judge rubric scores (architecture accuracy, abstraction quality, contribution quality, overall) via the Anthropic API against a pinned rubric.
The benchmark is frozen (eval/EVAL_SET.md): 22 public repositories pinned to exact
commit SHAs, from the single-file bottle up to dvc, each with a hand-written answer
key verified against the real code. Three local repos are kept as supplementary sanity
checks outside the headline set. repoco-eval report --gate exits non-zero below
grounding 0.95, entry-point recall 0.5, or key-file recall 0.4. No scorecard is
committed; metrics are produced per run.
cd backend && uv run pytest && uv run ruff check .
cd eval && uv run pytest && uv run ruff check .
cd frontend && npm run build # tsc --noEmit + vite buildCI (.github/workflows/ci.yml) runs all three on every push and pull request, plus
pip-audit on both Python packages and npm audit on the frontend. Actions are pinned
to commit SHAs.
One always-on process with a persistent volume: SQLite holds jobs and the prepaid
access-key wallets, and the event bus is in-memory, so it is never scaled past one
machine. The Dockerfile builds the SPA and serves it same-origin from the FastAPI
backend: one deploy, one origin, no CORS. DEPLOY.md walks through Fly.io end to end.
The deployed app is gated by access keys minted with uv run repoco keys mint, prepaid
token budgets of 2,000,000 tokens by default.
Python repositories only in v1; other languages sit behind the adapter interface but no other adapter exists yet. Ingestion refuses repos with more than 2,000 Python files, and GitHub fetches are capped at a 100 MB tarball and 500 MB extracted. Deterministic stages carry exact-assertion tests; the quality of the prose depends on the model behind the gateway, which is what the eval harness measures.
Full design in docs/superpowers/specs/2026-06-13-repoco-design.md; per-area notes in
eval/README.md and frontend/README.md; contributor workflow in CONTRIBUTING.md.
MIT.