speedread

speedread

Token-efficient code search and navigation for AI coding agents. speedread is an MCP server and CLI that gives Claude Code, GitHub Copilot, Codex, Cursor, Gemini CLI and other agents the part of a codebase a question needs, within a token budget: the function around each search hit, a large file's skeleton, a symbol's callers and implementations, or only what changed since the last read. Not whole files and bare grep hits.

`Read` is the wrong abstraction for coding agents. Agent code reading should be adaptive, stateful, symbol-aware and token-budgeted instead of byte-oriented. Every model call re-sends the system prompt, tool definitions and conversation so far (18–21k tokens before any code, in our evals), so an agent's cost is driven more by round trips than by bytes. ripgrep returns matches and cat returns bytes, so the agent asks again: open the file, find the function, search for the next hop. speedread returns *the minimum useful unit of code for the question*, with enough structure that the next call often isn't needed.

One of the ten code-question tasks, replayed from its recorded eval transcripts at recorded speed; all three trials of each condition behaved identically. The built-in grep answers with a file name, so the agent has to ask again, twice. speedread's search answers with the matching lines under their enclosing declaration. This is the second-largest saving of the ten tasks; two tasks came out about 1% worse, and across all ten, input tokens fell 35%. Full interactive report: brennengreen.github.io/speedread (also self-contained in demo/index.html), generated by demo/build.py from evals/results/.

Measured, not hand-waved

Real agents on real repositories, with the same model (claude-sonnet-5) and harness (GitHub Copilot CLI) in both arms: built-in tools vs speedread as the reader. Every trial, transcript, grader and diff is committed, including the workloads where speedread didn't help.

• Round trips drive the savings. speedread saves where it removes model calls: answers with enclosing context, batched reads, trace in one hop. On bug fixes, editing and testing dominate the turns, and read results were about 1% of input, so tokens barely moved.
• Adoption decides everything. An unused MCP server is not free: its tool definitions ride along on every call (+2.2k tokens per call, measured). Configure it as the reader.
• Scope. One model in one harness, and the relationship and bug-fix suites are small. Other clients and models are untested; treat these numbers as evidence for this setup, not a promise for yours.

pass^3 is the share of tasks whose three trials all passed. Intervals are 95% bootstrap intervals on the ratio of means (evals/stats.py). Per-suite detail: Results · method: evals/README.md · every table: evals/RESULTS.md · raw trials and transcripts: evals/results/

Quick start

1. Install (macOS on Apple Silicon, Rust 1.90+; a clean build took 80 s on an M4, plus downloads):

cargo install --locked --git https://github.com/brennengreen/speedread

or: brew install brennengreen/tap/speedread

Prebuilt binaries, a one-click Claude Desktop bundle, other platforms, and why the tap name: Install.

2. Add it to your agent as the reader, not as one more tool. Installed alongside the built-in tools with no guidance, it went unused and made runs more expensive (above).

# GitHub Copilot CLI: add the server, then remove the built-in readers (edit and bash stay)

copilot mcp add speedread -- speedread mcp copilot --excluded-tools view grep glob

Claude Code: keep Read, because Edit requires it

claude mcp add --scope user speedread -- speedread mcp claude --disallowedTools Grep Glob

VS Code, Cursor, Codex, Gemini CLI, Zed and Claude Desktop: Configuration. Where the built-in tools can't be removed, add the reading instructions to AGENTS.md, CLAUDE.md or .github/copilot-instructions.md.

3. Or try it by hand in any repository:

speedread map --symbols                      # structure, with each file's top-level definitions

speedread search 'handleRequest' # hits grouped under their enclosing function speedread trace '#handleRequest' --depth 2 # callers of callers; --direction callees|refs|impls speedread read 'src/app.ts#Server.start' src/util.ts:40-80 # several targets, one call, one budget

The primitives

Four tools over MCP, mirrored by the CLI:

read: batched, budgeted, symbol-aware

One call takes any mix of targets. They share one token budget (default 8,000).

A real skeleton of flask's 1,628-line app.py (excerpt) costs 3.4k tokens, against 21k for the file:

==> src/flask/app.py @… (1,628 lines) [skeleton]

110 class Flask(App): 111 """The flask object implements a WSGI application and acts as the central 112-205 ⋯ 366 def get_send_file_max_age(self, filename: str | None) -> int | None: 367 """Used by :func:send_file to determine the max_age cache 368-391 ⋯

Symbol-aware re-reads. After an edit, path@etag returns unchanged, the appended tail for a growing log, or a diff that names what changed. Hunks carry git-style function context, and mode=outline returns only the symbol summary. From tests/mcp.rs:

==> src/lib.rs @… (was @…): 1 hunk, +1 -1, now 131 lines

symbols: add [1-7]: body changed, signature unchanged @@ -2,5 +2,5 @@ add pub fn add(a: i32, b: i32) -> i32 { let c = a + b;

• let d = c;
• let d = c * 2; let e = d;

A signature edit reads f3 [25-27]: signature changed: `pub fn f3() -> u32` → `pub fn f3(k: u32) -> u32` ; a new function reads g [133-135]: added `pub fn g() -> u8` .

Etags are 64-bit. An etag is the full 64-bit xxh3 of the content, printed as 16 hex digits, and snapshots of what the agent has seen live in a 256 MB LRU keyed by it. Two *different* contents would have to collide in 64 bits to alias. Across 100,000 snapshots in one session that chance is about 3 × 10⁻¹⁰. Identical contents share an etag, which is correct. Shorter tags are rejected rather than prefix-matched.

search: hits grouped by enclosing symbol

$ speedread search 'def url_for|current_app.url_for\(' src/flask/helpers.py

3 matches in 1 file for /def url_for|current_app.url_for\(/ ==> src/flask/helpers.py @5dc322f9c9cf99f2 (3 matches) [200-251] def url_for(endpoint: str, *, _anchor: str | None = None, _method: str | None = None, _scheme: str | None = None, _external: bool | None = None, **values: t.Any) -> str 200 def url_for( 212 :meth:current_app.url_for() . See that method 244 return current_app.url_for(

output=symbols returns the full source of every enclosing function in the same call. output=files returns paths with counts.

trace: relationships, not text

The expensive agent loop is search → open → search again to follow a call chain. trace does it in one call. Real output on gin (abridged):

$ speedread trace '#AbortWithStatus' --depth 2

==> callers of Context.AbortWithStatus (context.go:221-227) func (c *Context) AbortWithStatus(code int) 14 call sites in 14 functions · syntactic: comments, strings and the definition excluded context.go [245-251] func (c *Context) AbortWithError(code int, err error) *Error 249 c.AbortWithStatus(code) ← [820-828] func (c *Context) BindUri(obj any) error 824 c.AbortWithError(http.StatusBadRequest, err).SetType(ErrorTypeBind) //nolint: errcheck … $ speedread trace Render.Render --direction impls ==> implementations of Render.Render (render/render.go:11-12) Render(http.ResponseWriter) error 19 implementations of Render · syntactic: types whose method sets cover the interface render/bson.go [13-16] type BSON [20-29] func (r BSON) Render(w http.ResponseWriter) error render/data.go [12-16] ty