Provides git-aware tools that read repository history: diff_impact identifies changed symbols between two refs or against the working tree, finds callers outside the diff, and dangling uses of removed symbols; hotspots ranks files by commits multiplied by lines inside methods.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@repo-compass find all call sites of Order.add in this repo, with confidence tiers"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that gives coding agents structural understanding of a codebase — symbols, references, module dependencies, diff impact, hotspots — plus an eval harness that measures whether it actually helps.
Under construction. See PLAN.md for the roadmap. Done so far: M0 (scaffold), M1 (indexer), M2 (MCP server), M3 (git-aware tools).
uv sync # add --extra agent for the anthropic SDK (API scripts only)Related MCP server: codebase-rag
uv run compass index path/to/repo # index Java + Python (incremental on re-run)
uv run compass symbol Order.add --repo path/to/repo --refscompass symbol accepts a simple name (add), a qualified suffix (Order.add) or search
words (getUser also finds get_user_by_id). --refs lists call sites, each labeled with
a confidence tier:
method com.example.shop.model.Order.add public Order add(Item item) .../model/Order.java:25
exact .../model/Order.java:36:13 add(...)
likely .../service/OrderService.java:17:19 order.add(...)The index is stored in your user cache directory (never inside the repository); --db
overrides the location.
From the repository you want to work on, register the server (replace the path with your repo-compass checkout):
claude mcp add repo-compass -- uv run --project /path/to/repo-compass compass serve --repo .--project (not --directory) keeps the working directory where Claude Code started, so
--repo . is your repository. There is no separate indexing step: the server indexes in
the background when it starts and refreshes before every tool call. The first call on a
large repo may reply "index building, retry" if the build takes more than a few seconds.
Eight read-only tools: repo_summary, search_symbols, get_symbol, find_references,
file_outline, module_dependencies, and two that read git history: diff_impact (changed
symbols between two refs or against the working tree, their callers outside the diff,
dangling uses of removed ones) and hotspots (files ranked by commits x lines inside
methods). Answers are compact text, ranked, and capped per
tool with an explicit [truncated: N more] line. Formats, ranking rules and token caps:
docs/tools.md. An end-to-end run in Claude Code on commons-lang and flask,
including what went wrong: docs/e2e-m2.md; for the git tools,
docs/e2e-m3.md.
Reference resolution is approximate. It uses names, imports, packages and scopes, not
types. exact means the binding is certain from syntax; likely means the target's class is
visible but the receiver's type is unknown; possible means only the name matches. There is
no type inference or override/dispatch analysis. Details and known failure cases:
ADR-003.
Only call sites are references. Type usages (parameters, extends, casts) are not.
module_dependencies sees import statements only. Java classes used from the same
package, or written fully qualified without an import, add no edge.
Tool token counts are estimated as characters / 3 (no offline Claude tokenizer), see ADR-005.
Outside a git work tree, .gitignore is not applied (ADR-004).
diff_impact finds changed symbols exactly (both versions are parsed), but their callers
come from the same approximate resolution, from the working tree's index, with no
override analysis. hotspots counts commits per file, not lines changed. Both need git.
Limits: docs/tools.md, ADR-007.
Java and Python only.
Indexing speed: about 2.4s for a 50k-line repo, and 7.3s for apache/commons-lang (207k lines). See docs/benchmarks.md, including the slower first run after a fresh clone.
uv run pytest -q # tests (includes a benchmark and a stdio test marked slow)
uv run pytest -q -m "not slow" # skip the slow ones
uv run ruff check . # lint
uv run ruff format --check . # format check
uv run python scripts/bench_index.py --synthetic 50000Design decisions are recorded in docs/adr/.
MIT
What a change touches: symbols changed between base and head (removed, signature, body, added), their callers outside the diff by tier, dangling uses of removed ones, importers. Compares the merge base, like a PR; head: a ref, default the working tree. Ranked: removed/signature changes with callers outside the diff first. <= 2000 tokens.
Inputs: base (required), head, limit.
Symbols a file defines, with line ranges and signatures, without reading it. Truncation keeps types, then methods, then fields. <= 1500 tokens.
Inputs: path (required), limit.
Call sites of a symbol, grouped by file, with calling symbol and source line. Tier: exact (certain from syntax), likely (type visible, receiver type unknown), possible (name only). Ranked exact>likely>possible, non-test first. <= 2000 tokens.
Inputs: symbol (required), limit.
Source of one symbol: body for methods/functions, member list for types, plus doc. symbol: 'Order.add', a qualified name, or path:line. <= 2000 tokens.
Inputs: symbol (required), max_lines.
Files that change often and hold much code: commits x lines inside methods, per file, renames followed. since: a ref or a date ('6 months ago'), default 1 year. Test files left out unless include_tests. <= 1200 tokens.
Inputs: limit, since, include_tests.
Import graph between packages/modules, and import cycles. No module: overview. module: a name, 'pkg.*' or a prefix: its imports, importers, external deps, cycles. Test files are left out unless include_tests. <= 1200 tokens.
Inputs: limit, module, include_tests.
Overview: languages, size, packages by lines, index freshness. Start here. <= 600 tokens.
Inputs: limit.
Find symbols by name: 'save', 'Order.add', or words ('get user' finds get_user_by_id). Returns file:line, kind, signature; no bodies. Ranked exact name, then word match; non-test first. kind: class|interface|enum|record|annotation|method|constructor|function|field. path: only in this dir, file or package ('model/', 'com.x.model'); with query '' it lists what path defines, types first. <= 1500 tokens.
Inputs: query (required), kind, path, limit.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 8 tools
Each tool targets a distinct analysis task: repo overview, symbol search/retrieval, file outline, reference lookup, module dependencies, churn hotspots, and diff impact. The overlap between find_references and diff_impact is minimal and contextually separated by change-focused vs. general reference lookup.
Names use snake_case throughout, but they mix verb_noun (search_symbols, get_symbol, find_references) with noun_phrase (diff_impact, hotspots, repo_summary, file_outline, module_dependencies). The convention is readable but not predictable as a single pattern.
Eight tools are well-scoped for a repository analysis server, with no obvious redundancy. Each tool covers a distinct and useful analysis capability, fitting comfortably in the recommended 3-15 range.
The set covers core static analysis needs: overview, symbol search, symbol retrieval, file outline, references, dependencies, churn, and change impact. Minor gaps exist, such as direct file content reading or type hierarchy/call graph queries, but agents can often work around these using other tools.
Codebase intelligence for AI agents — dead code, blast radius, ownership.
Deterministic context layer for your codebase: change impact, blast radius, answers with receipts.
Codebase intelligence for agents: 152 structured artifacts across 21 programs, one call.
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
