codescope
⭐ If codescope saves you context tokens, starring the repo helps others find it.
A single-binary, blazing-fast code-intelligence engine for AI coding agents.
🎬 Demo

codescope v0.1 indexing its own repo — 196 symbols, 1,322 edges in 188 ms — then a summary and a blast-radius query. Recorded from the actual binary with asciinema + agg. (The repo has grown since: at HEAD the same self-index is ~620 symbols / 4.5k edges in ~0.7 s.)
codescope indexes any repository into a precise, queryable structural graph and
serves it to AI agents over MCP (and CLI/JSON). Instead of letting an agent
grep blindly through files and burn its context window, it answers "who calls
this, what breaks if I change it, where is this defined, what does this module
depend on" in milliseconds — with token-budgeted output.
The precision of Sourcegraph, the install footprint of ripgrep, the interface of an MCP server, and no cloud, no database, no Python.
What's inside (v0.3): PageRank repo maps · natural-language find
(BM25F + centrality, no model needed) · git-diff change impact with the tests to
run · owner/receiver-aware call resolution (precision 1.00 / recall 0.97 on
the annotated eval suite) · an index that keeps itself fresh as you edit ·
10 languages · MCP 2025-06-18.
Capabilities
Languages (10): Rust, TypeScript, JavaScript, Python, Go, Java, C, C++, C#, Ruby (tree-sitter; see ADR-0019).
Every query is token-budgeted (--max-tokens, default 4000): results are
compact JSON with symbol, kind, file, line_start/line_end, edge lists,
and a truncated flag instead of dumping the whole graph.
Install
Prebuilt binaries (Linux x86_64/aarch64 static musl, macOS arm64/x86_64, Windows x86_64) are attached to every GitHub Release:
# example: Linux x86_64
curl -L https://github.com/adventurewave-labs/codescope/releases/latest/download/codescope-v0.3.0-x86_64-unknown-linux-musl.tar.gz | tar xz
sudo mv codescope-*/codescope /usr/local/bin/
From crates.io:
cargo install codescope-cli
From source:
cargo install --git https://github.com/adventurewave-labs/codescope
# or, from a checkout:
cargo install --path .
Usage
codescope index # build/refresh the index for the cwd
codescope -p /path/to/repo index # index a specific repo
codescope callers my_func --depth 2
codescope blast-radius src/auth.rs
codescope refs UserSession
codescope summary --max-tokens 4000
codescope search "kind:function calls:db.query returns:Result"
codescope callees do_thing --json # machine-readable output
codescope find "where do we parse the config file" # hybrid BM25F + PageRank
codescope find "delete user kind:method lang:python" # mix in structural filters
codescope map --max-tokens 1500 # ranked repo map (Aider-style)
codescope map src/auth.rs login # map personalized to what you're editing
codescope diff-impact --base main # what your branch changed/affects + tests to run
codescope watch # re-index incrementally on every save
codescope status # fresh / stale (stat-only check)
Structural search
Space-separated terms; key:value are filters, bare words match name/signature:
kind:function|method|struct|enum|trait|interface|class|module|type|constant|fieldlang:rust|typescript|javascript|python|go|java|c|cpp|csharp|rubyfile:<substr>·name:<substr>·calls:<callee>·returns:<type-substr>·owner:<Type>(aliasin:)
Symbol targets accept qualified names: codescope callers Store::open, codescope refs store::open.
codescope search "kind:method lang:rust calls:spawn returns:Result"
MCP server (for agents)
codescope speaks MCP over stdio (newline-delimited JSON-RPC). Start it with:
codescope serve --mcp
Register it with any MCP-capable agent (Claude Code, Cursor, Windsurf, VS Code/Copilot, Cline, Zed, Continue). With Claude Code:
claude mcp add codescope -- codescope serve --mcp -p /abs/path/to/your/repo
Or in a JSON MCP config:
{
"mcpServers": {
"codescope": {
"command": "codescope",
"args": ["serve", "--mcp", "-p", "/abs/path/to/your/repo"]
}
}
}
No cs_index call is needed: the server builds the index on first use and,
before each answer, runs a cheap stat check and incrementally patches in any
files changed since (every result carries freshness; ADR-0020). See
docs/mcp.md for the full tool reference.
Recommended agent loop (also sent as the server's instructions):
- Orient —
cs_repo_map(passfocus= the files/symbols you're touching). - Locate —
cs_find "what the code does", orcs_definitionif you know the name. - Before editing —
cs_callers/cs_blast_radiuson what you'll change. - After editing —
cs_diff_impact→ changed symbols, dependents, and the tests to run.
Performance
Measured on a 4-core container (release build) — see docs/BENCHMARKS.md:
- Cold index 100k LOC in ~0.2 s; ~1M LOC in ~1.6 s. Expect roughly linear slowdown on smaller machines: a 2-core Codespace indexes 125k dense LOC in ~0.9 s and a 1.15M-LOC / 1.2M-edge corpus in ~17 s.
- Incremental re-index of one changed file in ~55 ms; queries auto-refresh after edits (stat check ~4 ms / 1-file patch ~36 ms on a 264-file Java repo — see ADR-0020).
- In-process query latency < 2 ms for every query type on that hardware —
graph traversals are µs-scale; the two full-scan queries (
search,summary) land at ~1.4–1.7 ms on 4 cores and ~1.2–6.8 ms on 2 cores. - On-disk index size is the one PRD target not met (~75% vs. <15%); the cause and remediation are documented honestly in the benchmarks doc and ADR-0005.
Accuracy
Call resolution is measured on annotated multi-file fixtures in all 10 languages
(tests/eval/, 85 call sites incl. same-name methods across classes, module-
qualified calls, field receivers, trait objects, and std-lib calls that must
stay unbound) — see docs/EVAL.md:
find relevance on 16 behavior-phrased queries over codescope's own source:
MRR 0.70, Recall@5 0.88. Both are regression-gated in cargo test; run
scripts/eval for the full report.
How it works
repo → Walker (ignore-aware, parallel) → tree-sitter parsers → symbols, docs, edge sites
→ Resolver (owner/receiver/import-aware, abstains when unsure)
→ CodeGraph (in-memory, indexed) ⇄ redb (embedded, on-disk)
→ PageRank · BM25F search · diff impact · freshness (stat check + incremental patch)
→ Query API → CLI / JSON / MCP
- Parsing: tree-sitter (robust error recovery, incremental).
- Resolution: two-tier — fast tree-sitter heuristics now (labeled
heuristic: owner/receiver-aware, import-aware, local receiver-type inference, and import edges that bind only with in-repo evidence — a qualified path likestd::process::Commandstays unbound rather than captured by an in-repo namesake, and imports never bind across language families; ADR-0018, ADR-0023), with a SCIP precision tier designed in (labeledprecise). - Storage: embedded, single-file, memory-mapped redb. No external DB.
- Concurrency: rayon for parallel parsing/extraction, resolution and search indexing.
- Ranking & search: personalized PageRank (repo map, summary), BM25F over identifier subtokens + doc comments fused with centrality via RRF (ADR-0015, ADR-0021).
Documentation
- Architecture Decision Records:
docs/adr/(22 ADRs). - Domain-Driven Design:
docs/ddd/— ubiquitous language, bounded contexts, domain model, services & repositories. - Benchmarks & validation:
docs/BENCHMARKS.md· accuracy reportdocs/EVAL.md(scripts/eval). - Releases: tag
vX.Y.Z→.github/workflows/release.ymlbuilds and publishes binaries for 5 targets (ADR-0022). - Product requirements:
plans/codescope.prd.
Ecosystem
License
Dual-licensed under either MIT or Apache-2.0 at your option.