Astrolabe AI

Astrolabe AI is a local MCP server that gives Claude Code, Cursor and Codex fast code search, symbol lookup and reference navigation, with directory-level counts for questions like "how many call sites per module". It is a single Rust binary (astrolabe) that indexes your repo with tree-sitter and starts language servers on demand.

简体中文 · Install guide · FAQ · Benchmark harness · Changelog

Not to be confused with the npm packages astrolabe (a 2014 Protractor page-object library) and astrolabe-ai (an unrelated resume tool), or other MCP servers named "astrolabe". This project lives at github.com/wojiushirencai/Astrolabe; the binary is astrolabe.

1. Install (macOS / Linux; verifies the release sha256):

curl -fsSL https://raw.githubusercontent.com/wojiushirencai/Astrolabe/main/install.sh | sh

Other ways (manual download, Windows, build from source): docs/INSTALL_GUIDE.md. An npm package @astrolabe-ai/astrolabe is prepared but not published yet.

2. Connect your client. Claude Code:

claude mcp add --scope user astrolabe -- astrolabe . --context=claude-code

Cursor (.cursor/mcp.json): {"mcpServers":{"astrolabe":{"command":"astrolabe","args":[".","--context=cursor"]}}}. Codex, Windsurf and others: docs/INSTALL_GUIDE.md.

3. Verify. astrolabe --version prints the version; in your client, ask it to call get_languages or search_code. Restart the client session after adding the server.

All numbers below come from our own paired A/B runs: A = Claude Code without Astrolabe, C = the same task with Astrolabe connected. Cost is Claude Code's total_cost_usd, time is duration_ms. One model was used: gemini-3.8-flash-high through Claude Code and an Anthropic-compatible proxy (so USD figures use that proxy's pricing). WebSearch/WebFetch were disabled in every arm. Summaries of the reports are in bench/results/ and the method in bench/README.md.

Simultaneous pairs on v0.13.0: 15 tasks, 95 pairs. 11 tasks with 5 pairs each and 4 tasks (N5, N8, N4, E3b) with 10 pairs each. Each pair started A and C at the same instant.

Equal weight per task gives a similar picture: cost −$0.45 [−0.90, −0.15], time −76 s [−153, −21]; C is cheaper than A on average in 11 of 15 tasks. Dropping the pairs that overlapped a machine freeze changes little (87 pairs: cost −$0.45, time −87 s).

Primary vs strict scoring (N5): the reference answer for N5 counts 2 call sites that sit inside comments (model=15/44, total=321). With skip_comments=true Astrolabe returns 15/43 and 319, which is also a defensible answer. The primary N5 verdict therefore accepts either convention; the strict verdict (reference convention only) is still computed and reported next to it. The whole strict gap comes from N5 (C 1/10 strict, 10/10 primary). We changed the N5 primary after seeing this result; both numbers are published so you can judge it.

Where the gain is. It is concentrated in aggregation/discovery tasks: N1 (cost C − A −$3.10 [−4.88, −1.32] over 5 pairs), N5 −$0.64 [−1.22, −0.02], N8 −$0.91 [−1.48, −0.31] over 10 pairs each. The other 10 of the 11 newly added tasks have cost intervals that include zero, and simple locating/small tasks (H2, H3, H6, H7, E2, N6, N7) are about even. N4 and E3b (private repos) were cheaper on average but not significantly, and in them the model never used the aggregate options. Per-turn latency did not differ (+0.6 s [−0.3, +1.4]); the time saving comes from fewer turns.

What this does not show.

• It does not show a general benefit. The 15 tasks are our own, there is one model, and each task has only 5 or 10 pairs, so per-task intervals are wide. Treat the averages as describing these tasks only.
• The older v0.12.0 matrix (75 cells, 15 tasks, 5 rounds, triplets started together) found Astrolabe more expensive, not cheaper: cost C − A = +$0.244 [+0.035, +0.467]; time +53 s [−8, +119] and correctness −4.0 points [−10.7, +2.7] both include zero. On its 40 control cells the extra cost was +$0.294 [+0.085, +0.540]. Newer results used v0.13.0, which changed search_code and the tool list, so the two runs are not the same product.
• Six of the 15 tasks use private or edited code (N4, E3b, H4, H5, E1, N7) and cannot be reproduced by others. The public-repo tasks can be re-run. The reference snapshot we used was a local copy; see bench/README.md for how to check your checkout against it.
• Latency per turn drifts during the day, so only simultaneous pairs are comparable for time.

Reproduce the public part: bash bench/fetch_corpora.sh && bash bench/run_pairs.sh --tasks N5,N8 --pairs 10 (real API spend: our 40-pair run cost about $214, the 55-pair run about $121), then python3 bench/report.py.

• Measured to help: counting or listing occurrences per directory/module with exclusions (N5, N8) and one broad discovery task (N1): fewer turns and lower cost than the same model doing it with shell scripts.
• Not shown to help: simple locating or small-edit tasks (H2, H3, H6, H7, E2, N6, N7 are about even, intervals include zero); the 40 general-purpose control cells of the v0.12.0 matrix cost more with Astrolabe; batch edit workflows (N4, E3b) were cheaper on average but not significantly.
• Overlap: Claude Code can provide go-to-definition and find-references through its own LSP plugins (docs); our goto_definition / find_references overlap with that.
• Adoption is not guaranteed: models sometimes ignore MCP tools. In v0.12.0 the model used Astrolabe in 0/5 runs of N5 and 1/5 of N8; with v0.13.0 it did so in 92 of 95 runs across the 15 tasks. That is an observation about this model and these tasks, not a promise.

Serena (LSP-based coding toolkit), codebase-memory-mcp, codegraph, claude-context, the Sourcegraph MCP server, and Claude Code's built-in LSP plugins. We have not benchmarked Astrolabe against any of them; indexing-time numbers that older versions of this README published against Serena and OpenVisio are archived with their caveats in docs/PERFORMANCE.md.

Install & clients · FAQ · Reference (Chinese): config, env vars, language matrix, quality gates · Architecture · Performance method · Optional anti-drift hooks (effect not benchmarked) · Releasing · llms.txt

Build from source: cargo build --release --bin astrolabe (Rust 1.90+). Tests: cargo test --workspace.

MIT OR Apache-2.0, see NOTICE. Astrolabe was inspired by Serena and OpenVisio; details in docs/REFERENCE.zh-CN.md.