On August 9, 2026, Ahmad Awais shared a deep dive on X about the read tool in Command Code, his coding agent. The claim is big: the read tool saves billions of tokens a month compared to Claude Code. The full post now lives in the Command Code docs.
This article is my summary of that post, written in simple English. If you build agents, or just use them, the lessons are useful.
Why a read tool matters
Coding agents read files all the time. Every edit starts with a read. Every search result becomes a read. A plan step opens three files. Command Code sees about 50 million reads a month.
Each read costs tokens. If one read brings in 500 useless tokens, that is 25 billion useless tokens a month. Worse, those tokens stay in the conversation, and they cost tokens again on every later turn.
That is why coding agents feel expensive. The bill is mostly reads, not clever reasoning.
Think of the read tool as a compiler. It turns your files into the model's context. Every small choice inside it is a token decision, repeated millions of times.
The difference: spend more vs spend less
Claude Code's read tool is simple. Ask it to read a 3,000-line file, and it returns all 3,000 lines. Ask for a file with a 3,900-character minified line, and it returns the whole line. No limits at all.
That works for Claude Code because its models are strong enough to ignore the noise. It spends more tokens to succeed.
Command Code runs on open models. Those models cannot handle a messy read. Users also pay for every token. So Command Code had to spend less. That one constraint forced every design decision below.
What Command Code's read tool does differently
- Three limits, not one. 2,000 lines per file, 128 KB per read, 2,000 characters per line. Each limit stops one kind of bad file: big files, wide files, and minified one-line files.
- Clear messages instead of silence. If a file is empty, it says "file is empty". If the read goes past the end, it says "try a smaller offset". The model knows what happened and what to do next, so it stops guessing and retrying.
- Auto-retry for tricky filenames. macOS names screenshots with special characters that look normal but are not. The tool retries 7 versions of the name before giving up.
- "Did you mean?" for typos. If a file is not found, it suggests close matches. This catches mistakes like AGENT.md vs AGENTS.md.
- Refuses dangerous files. It will not read /dev/zero or /dev/urandom. These files never end, so reading them would hang the agent forever.
- Caches that expire on use. If the same file is read twice, the second read returns a short note. But the note removes itself after one use, so the model never points at old context forever.
- Images are compressed, not dropped. A 4K screenshot is compressed step by step until it fits. The tool also tells the model the new size, so clicks on the image still point to the right place.
- Notebooks become clean documents. Raw .ipynb files are messy JSON. The tool returns labeled cells and attaches plots as images, so one big table cannot eat the whole read budget.
The benchmark
Command Code compared its read tool with nine other harnesses: Claude Code, OpenCode, Cline, Kilo, Codex, Grok, Hermes, pi, and OpenClaw. Most have the basic limits. Very few have the extras: retrying filenames, clear recovery messages, or blocking dangerous files.
Those extras do not show up in a demo. They matter in hour nine of a long session, when a read fails and the model needs a way back.
One honest note: the page says the benchmark itself was produced by AI with little human review, and the authors expect some errors. The read tool itself was reviewed by a dozen engineers over a full release cycle.
What you can learn
- Give your tools recovery messages. A tool that fails should say what happened and what to send next. Silence makes the model guess.
- Fix the invisible failures. If a problem is invisible to the model, fix it in the tool, not in the prompt.
- Check the cheap things first. Limits, input checks, and a blocklist of dangerous paths stop expensive loops.
- Constraint is a feature. Being forced to save tokens made Command Code build a better tool.
My take: the read tool looks boring, but it is the most important part of an agent harness. This post is the best explanation I have seen of why.
Which tool in your agent's harness would you check first? I would start with the one that returns empty results.
Top comments (0)