speedread 0.1 — token-efficient code navigation for coding agents

speedread is an MCP server and CLI for AI coding agents such as Claude Code, GitHub Copilot, Codex, Cursor and Gemini CLI. Instead of whole files and bare grep hits, it returns 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.

Why

Every model call re-sends the system prompt, tool definitions and conversation so far, so an agent exploring code pays mostly for round trips, not bytes. File-oriented tools add round trips: grep returns a location, a read returns a page, and the agent asks again. speedread's answers carry the enclosing structure, so the next call is often unnecessary.

What's in 0.1

• map: a budgeted, .gitignore-aware repository tree with line counts, and each file's top-level definitions on request.
• search: ripgrep's engine, with every hit grouped under its enclosing function or class and its line range.
• trace: callers (up to three levels), callees, references and implementations, including structural Go interfaces. Syntactic and receiver-aware; ambiguous sites are marked ?.
• read: files, line ranges, path#Symbol, #Symbol, Markdown sections, JSON/YAML/TOML keys and globs, batched under one token budget. Files that don't fit come back as skeletons, never blind cuts; path@etag returns only what changed, labelled by symbol.
• Outlines via tree-sitter for Rust, Python, JavaScript, TypeScript/TSX, Go, Java, C, C++, C#, Ruby, PHP, Bash, Swift, Kotlin, Scala, Lua and Objective-C, plus Markdown, JSON, YAML and TOML.
• A token estimator checked on adversarial content (0 of 525 reads over budget), with a Claude profile calibrated on production token counts.
• Read-only by construction: no write tools, and paths must resolve inside a workspace root or a dependency cache (--no-deps turns the latter off).
• A CLI that mirrors the tools and emits JSON Lines for scripts, and an Agent Skill.

Measured

Real agents, same model (claude-sonnet-5) and harness (GitHub Copilot CLI) in both arms: built-in tools vs speedread configured as the reader.

Workload	Trials per arm	Input tokens	Model time (median)	Quality
Code questions	30	−35% (95% CI −45 to −23%)	−47%	pass^3 90% → 100%
Relationship questions	8	−57% (CI −74 to −20%)	−34% (not significant)	100% → 100%
Bug fixes, with guidance · exclusive	16	−3% · −1% (not significant)	−24% · −27% (not significant)	100% → 100%
Installed but not made the reader	10 · 16	+31% · +46% (higher on 9 of 10 · 8 of 8 tasks)	—	used in 0 of 26 trials

• Savings come from removed round trips: they're largest when the agent explores code, and small when editing and running tests dominate.
• Installing speedread without making it the reader made runs more expensive, because its tool definitions are sent on every call.
• One model in one harness, and small samples for relationships and bug fixes. Other clients and models are configured but not measured.

Method: evals/README.md · all tables: evals/RESULTS.md · raw trials, transcripts and diffs: evals/results/

Install

Prebuilt for macOS on Apple Silicon (attached below, with its SHA-256):

mkdir -p ~/.local/bin   # or any directory on your PATH
curl -fsSL https://github.com/brennengreen/speedread/releases/download/v0.1.0/speedread-aarch64-apple-darwin.tar.gz | tar -xz -C ~/.local/bin

The binary isn't notarized; if you download it with a browser rather than curl, clear the quarantine flag with xattr -d com.apple.quarantine speedread.

Claude Desktop: download speedread-aarch64-apple-darwin.mcpb (attached below) and open it. Claude Desktop asks which folder speedread may read.

From source (Rust 1.90+):

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

Homebrew (builds from source): brew install brennengreen/tap/speedread. Use the full name: brew install speedread installs an unrelated RSVP speed-reading tool from homebrew-core.

Then make speedread the agent's reader, not one more tool:

# GitHub Copilot CLI
copilot mcp add speedread -- speedread mcp
copilot --excluded-tools view grep glob

# Claude Code (keep Read: 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.

Supported environments

• macOS on Apple Silicon: built, tuned and tested in CI (macOS 15).
• macOS on Intel: the test suite passes as an x86_64 build under Rosetta 2; not yet tested on Intel hardware.
• Linux: the test suite passes on Ubuntu 24.04 (x86_64); install from source. Reports welcome.
• Windows: not supported.

Known limitations

• trace is syntactic, with no type inference; calls inside closures are attributed to the enclosing named function.
• The tool definitions add about 2.2k tokens to every model call, whether or not they're used.
• In Claude Code, Edit requires a native Read first. On edit-heavy work, expect speedread to save turns and time rather than tokens there.
• Budgets are calibrated estimates, not tokenizer counts.

Feedback

Bug reports, client setups and eval results from other harnesses and models are all welcome, including results where speedread doesn't help: open an issue.