Why
An AI coding agent learns a codebase by grep and by reading files, and every later request sends all of that reading again. codefast answers from an index instead.
- One exact answer. The definition, every call site with its code line, the call path, the tests that reach it. Checked against compilers: precision 0.982 to 1.000.
- Before the agent asks. Hooks hand over the facts with the prompt, after a search, after an
edit and after a compaction, when a session also gets its requests back word for word. A
sub-agent gets them too, for its brief. They state facts and never block a tool call. In Claude
Code one line is also added to what the harness runs before each shell command, so that in zsh
a pattern that matches nothing is passed on as typed, as in bash (
CODEFAST_SHELL_SETUP=offleaves the shell as it is). - Any size. The Linux kernel, 44 million lines, indexes in 8 seconds, and the index follows your edits.
- Measured, with what it does not do. On held-out lookup tasks a Claude Code session with Haiku 5.5 costs 0.15 to 0.71 of the same session without it, and about half with Sonnet 5.5 and Opus 5.5. A session that writes or fixes code costs the same as before, and on architecture questions about code the models already know, Opus 5.5 is as quick and as cheap without it. Results has every figure with its day and its caveat.
Quick start
# 1. Install the binary: macOS or Linux, no sudo, SHA-256 checked
curl -fsSL https://raw.githubusercontent.com/YashSharmaa/codefast/main/install.sh | sh
# 2. Register it with your harness
claude plugin install codefast --marketplace YashSharmaa/codefast # Claude Code
codefast setup codex --hooks --apply # Codex
codefast setup --all --apply # every harness found
That is all. The index builds itself on first use, and the agent reaches codefast through its
shell, through the MCP server (codefast mcp) or through the hooks.
codefast setup --list names the 32 harnesses it can set up (Cursor, Gemini CLI, OpenCode,
Copilot CLI, Goose and more). codefast setup without a name prints the plan for the harnesses
it finds and changes nothing, codefast setup NAME --print does that for one of them, and
codefast doctor shows what is in place. docs/INSTALL.md covers every
harness and says for each what was tested.
The installer fetches release 0.4.0. Four things on this page are on main and come with the
next release: the zsh line, what a sub-agent is told at its start, the requests given back word
for word after a compaction, and the looks in a row and the hours in doctor sessions.
What it answers
| You want | Run |
|---|---|
| Everything about a symbol, a file or free text | codefast search NAME |
| All the reading before an edit, in one answer | codefast context NAME |
| Who calls it, also through ops tables and callbacks | codefast callers NAME |
| How execution gets from A to B | codefast path A B |
| Which function prints a message | codefast grep -F "text of the message" |
| The files a bug report points to, with the source that says so | codefast locate "paste the report" |
| A rename everywhere it is surely meant | codefast rename Owner.name NewName |
| What the uncommitted edits broke or left behind | codefast check |
| The API of an installed dependency | codefast dep NAME SYMBOL |
| The parts a repository falls into, what everything goes through, unexpected couplings and import cycles | codefast map (--html FILE draws it) |
| What your harness configuration costs per request | codefast doctor context |
| Where the tokens of your sessions went, and which habits cost the most | codefast doctor sessions |
The agent gets the same answers through five MCP tools (search, show, refs, path, grep),
and without asking through hooks: a prompt that names a symbol comes with its definition and its
uses, a search comes with what it did not print, an edit with the places it left broken.
The map of a repository, drawn: codefast map --html map.html
One file that opens without a network: the groups come from the resolved call graph, a click on one lists its files and its most used definitions, and the side panel has the hubs, the unexpected couplings and the import cycles. The Linux kernel takes 27 seconds. The idea of such a map is Graphify's. This one is asked for and never pushed into a session, and it is computed from calls the index has resolved.
The six moments at which a hook adds facts, with what it prints
Where your tokens go
Most of what a long session costs is not the work. It is the conversation sent again with every
request, and a few habits nobody shows you: coming back after the prompt cache has expired,
switching models in the middle of a job, carrying a conversation of half a million tokens, a
sub-agent that waits ten minutes on a build, thinking that is billed as output. codefast doctor sessions reads the transcripts your harness keeps on your machine and puts numbers on each, with
the one thing to do about it. It tries an earlier compaction at several lengths on your own
sessions, and for Claude Code it prices every request as its own model does, reads every sub-agent
as the conversation it is, and says how many requests were one look after another and where the
hours went. Nothing is
run, nothing leaves the machine, and no model is called.
What the report looks like
Claude Code sessions of this project in the last 14 days: 1 session, 172 main-thread requests, 7.5M weighted tokens.
main thread 7.1M cache reads 2.8M (37%), cache writes 3.5M (47%), output 805k (11%)
sub-agents 411k 26 requests (5%), 2 agents with transcripts of their own
Where it went, largest first, as a share of the 7.5M in all:
2.2M 29% Cold restarts: 3 requests sent the conversation again at the price of new input:
2 model switches (1.6M), 1 idle for more than an hour (528k).
Come back within the cache lifetime or start fresh. Finish a job on one model.
1.6M 21% Carried context: 123 of 172 requests (72%) carried more than 200k tokens, at most 640k.
Compacting at 200k instead: 3 more compactions for about 261k, and about 1.8M less
to pay for after them, so about 1.6M less in all (an estimate).
`/autocompact 233k` moves it there.
537k 7% Thinking: 107k of 179k output tokens (60%), billed as output at 5 times the input price.
180k 2% The start, 21k tokens, was read again from the cache by 171 requests.
`codefast doctor context` shows what the start holds and what can be switched off.
80k 1% Cold restarts in sub-agents: 1 request of sub-agents sent the agent's conversation
again at the price of new input: 1 idle for more than five minutes (80k).
A sub-agent's prompt cache lasts five minutes here, counted from when a request is
sent: 1 followed a tool call that took longer than that.
A long command costs less run in the background with a look every few minutes.
A weighted token is one uncached input token of the request's own model, with each kind of token weighed as that model's price list weighs it: here a cache read 0.05, a cache write 2 and an output token 5. The example is a made-up project, and some lines are shortened.
In Claude Code the hooks also say it at the moment it matters, to you and not to the model: what
every request pays to read a long conversation again and how soon a /compact would pay for
itself, that the next request sends everything again because the prompt cache has run out, and
that a conversation on Claude Haiku 5.5 is about to pass the 100,000 tokens above which that model
charges five times as much. Once a week you are told in one line what the sessions of the last
seven days mostly cost. The figures are those of the model the conversation runs on. One of these
facts goes to the model too, because only the model can act on it: that a command, or its own
reply, took longer than the prompt cache lives, which for a sub-agent is five minutes, and that
the next long one costs less in parts. And a sub-agent is told at its start how to wait inside
those five minutes, unless your settings give sub-agents the one-hour cache.
codefast doctor context is the other half: what your plugins, skills, sub-agents,
instruction files and memory index add to every request, and the setting that switches each off
for this project, where the harness has one. MCP servers are counted and not costed, since their
tools load only when they are used.
Results
Every benchmark, what it found and what to hold against it. BENCHMARKS.md has
the protocols, the full tables and what was tried and not kept. The raw rows are in
bench/results/, with one script per benchmark in bench/.
| Benchmark | Result | Hold against it | Measured |
|---|---|---|---|
| Claude Code sessions that find things7 kinds of held-out task, Haiku 5.5 | A session with the plugin costs 0.15 to 0.71 of the same session without it, with answers as right (the chart) | 3 to 18 tasks a kind. Cost is priced per request: a cached token 0.1, a new one 1.25, an output token 5 | 13 and 14 Nov 2026 |
| Claude Code sessions that locate a bug report48 kernel reports, 40 issues of Python projects | 0.77 and 0.84 of the control | Cheaper, and the file is not found more often: 0.73 against 0.77 on the kernel | 14 Nov 2026 |
| Claude Code sessions that write or fix code20 functions to write, 15 bugs to fix | 1.03, 0.93 and 0.92 of the control | No saving. None of the three can be told from 1.00 | 13 and 14 Nov 2026 |
| Claude Code sessions that build a project from nothing6 held-out projects in four languages, Haiku 5.5 | 0.98 of the control, with the hidden tests passed as often (211 and 210.5 of 211). All 10 projects with the build before 15 Nov: 1.03 | No saving, and none to expect: a project that does not exist has nothing to index. The plugin adds 224 tokens to the start of such a session (734 before 15 Nov). Two runs a project and arm, the control from the night before | 15 Nov 2026 |
| A development conversationa project and five changes to it in six messages, 4 held-out projects, Haiku 5.5 | 1.00 of the control with the plugin (0.92 to 1.08, 8 runs against 16), every hidden test passed (376 of 376). Sonnet 5.5: 0.94 in dollars (0.90 to 1.01), 0.92 of the time | No saving: the session wrote the code it is asked about. The same control run twice differs by 8%, so read this as no difference. The build before 15 Nov measured 1.08: its hooks commented on code that was still being written (3,516 bytes a conversation, now 63) | 15 Nov 2026 |
The shape of that conversationwhat doctor sessions and the notes point at, 4 held-out projects | Compacted under the model's price step (/autocompact 125k): 0.39 of the dollars. With the plugin, whose hook gives the request back after each compaction: 0.36, and the hidden tests of the one conversation (375.5 of 376, against 373.5 without the hook) | Claude Haiku 5.5 only, which charges five times as much for a request over 100,000 tokens. In tokens the shape costs more (1.19 of the one conversation), so without that step it does not pay at this size. 8 conversations a shape | 15 Nov 2026 |
| The same four kinds of task with every model37 held-out tasks: a caller question, four in one session, an error traced, a rename | Time and cost of a session with the plugin against the same session without it. Haiku 5.5: 0.36 and 0.31. Sonnet 5.5: 0.52 and 0.42. Opus 5.5: 0.56 and 0.50. Answers as right with each | One run per task and arm for Sonnet and Opus. Opus was measured before four changes that reading its sessions led to. Fable 5.2 was not run | 13 to 15 Nov 2026 |
| The seven-repository protocol another tool publishesone question about the architecture of VS Code, Excalidraw, Django, Tokio, OkHttp, Gin and Alamofire each, four runs an arm | The session without any tool now takes 45 s, 3.2 tool calls and 0.14 dollars with Opus 5.5, where the published session with the tool takes 28 to 63 s and 31 to 66 cents. Against it codefast takes 0.79 of the time with Haiku 5.5, 0.84 with Sonnet 5.5 and 0.97 with Opus 5.5 | The published saving (0.47 of the time, 0.57 of the cost, Opus 4.8) is against a session of 6 to 43 tool calls. Seven questions about code the models know. With Opus 5.5 codefast is level with the control, not under it: 1.03 of its cost and 1.12 of its tokens (1.16 and 1.14 that morning, before the answers to several symbols at once were changed: the evening's rows took the place of that run's). Sonnet and Haiku were measured before that change | 15 Nov 2026 |
| Codex sessions54 held-out question tasks, gpt-6.1-sol | 0.81 of the control (0.76 to 0.85 at 95%), every answer right in both arms | Question tasks only. Codex never called the MCP server: the saving came from the prompt card and the command line | 14 Nov 2026 |
| agent-context-bench, published26 graded questions on apache/superset | Lookups 1.00 and hard tasks 0.98, where the best published arm has 1.00 and 0.94, at the lowest cost of a task | One repository. The other arms are their published figures | 14 Nov 2026 |
| LinuxFLBench with an agent, publishedits own protocol, 104 kernel bug reports nothing was developed on | The file of the fix is among the ten candidates for 0.82 of the reports. With no map: 0.58. With the paper's best map, built from its code and run here: 0.74. Tokens: 14% fewer than no map, 17% fewer than that map | Version 0.3.1 was changed for this task. Over the paper's map the lead in finding the file is at the edge of what 104 reports show (+0.08, between 0.00 and 0.15). Dollars are level with no map | 14 Nov 2026 |
| Indexing the Linux kernel44 million lines | 8.0 s into 0.6 GB. The next fastest tool measured here takes 34 s | One machine (Apple M5 Max, 18 cores). The other tools ran under load, so read it as a ranking | 13 Nov 2026 |
| 72 verified kernel questions, one call each | 0.96 right at a median of 155 tokens. ripgrep typed by an expert: 0.89 at 384 | The other five tools got one direct query each, not a tuned workflow | 13 Nov 2026 |
| Call graph against compilersredis, gitleaks, syft, go-git, zod | Precision 0.982 to 1.000, recall 0.969 to 1.000 on direct calls | Calls through interfaces are a separate list of candidates: with them, recall on syft is 0.885 at a precision of 0.883 | 13 Nov 2026 |
| Files for a bug report, no model | LinuxFLBench: right file first for 0.344 (best published 0.228). Loc-Bench, 243 held-out tasks: 0.733 (0.609). ContextBench: 0.898 (0.876) | The other figures are the published ones, not run again here | 13 Nov 2026 |
What this says. Where the work is finding things, a session costs 0.15 to 0.71 of what it did on
the held-out tasks, and the longer it runs the more it saves, because what an agent reads early is
sent again with every later request. Where the work is the model's own, writing a function, fixing a
bug or building a project, the plugin costs nothing and saves nothing: there is nothing to look up
in code that is being written. What moves the bill of such a session is its shape, how long the
conversation gets and where it is cut, and that is what codefast doctor sessions measures on
your own sessions and what the hooks say at the moment it matters. On Claude Haiku 5.5 the setting
they point at took a held-out development conversation to 0.36 of its dollars with the same hidden
tests passed.
Requirements
| What | Needed |
|---|---|
| System | macOS or Linux, arm64 or x86-64. On Windows, build from source (not tested) |
| Install | One download of about 6 MB. No runtime dependencies, no sudo |
| Model, key, network | None. codefast never calls a language model and needs no network after the install |
| Harness | Anything that runs a shell command or speaks MCP. Hooks for Claude Code and Codex, checked with Claude Code 2.1.323 and Codex CLI 0.164.0 |
| Project | Any directory. In a git work tree, check and changed compare with the last commit |
| Index | Built on first use into .codefast/ inside the project, which ignores itself in git. Kubernetes, 7 million lines, takes 1.3 s. The kernel takes 8 s, 3.7 GB of memory and 0.6 GB of disk |
| From source | cargo install --git https://github.com/YashSharmaa/codefast |
How it works
- Facts, linked by name. tree-sitter parses each file alone into definitions, references and imports. A changed file is read again alone, so the index never needs a full rebuild.
- Linking at query time. A reference is tied to its definition when you ask: by scope, imports, package, receiver type, arity and include reachability.
- Callbacks are edges. A function stored in an ops table or passed as a callback is linked to the places that call through that slot.
- Answers sized for a context window. Plain text,
path:linelocations, a token budget, and an exact count of what was left out.
Languages. C, C++, Python, JavaScript, TypeScript, Go, Rust, Java, Kotlin, C#, PHP, Ruby and
Swift each have a full extractor and share one index, so a project that mixes them works without
configuration. Vue, Svelte and Astro components are read too. C is the most mature.
BENCHMARKS.md says how each language was checked.
Limits
- It reads syntax, not types. A call through a value whose type only a compiler knows is
counted and not tied to its target (
codefast refs NAME --looselists those). - It does not run builds. Code generated at build time is not indexed, and macros that paste tokens can hide a definition.
- The plugin does not make writing code cheaper. Where there is nothing to look up it adds 224
tokens to the first request of a session that starts in an empty directory, and about 800 in a
repository with code, where one tool and a paragraph of instructions are loaded from the start.
It changes nothing else. What changes the bill of such a session is its shape, which
doctor sessionsmeasures. - The live figures are from two harnesses, and most of them from one small model. Single tasks vary by a factor of two between runs.
BENCHMARKS.md has the full list.
More
docs/INSTALL.md: every harness, building from source, what was tested and how.docs/HARNESSES.md: what each harness gets and which file it reads.BENCHMARKS.md: every measurement, the research each design choice answers, and the limits.bench/tier2/LIVE.md: the protocol of the live sessions, and everything that was tried and not kept.AGENTS.mdanddocs/agents/: the contributor guide.
Licence
MIT or Apache-2.0, at your option. See LICENSE-MIT and
LICENSE-APACHE.