A build prints a thousand lines. One test fails. You paste everything into Claude and ask which test failed. A colleague gives Claude only the failed test name and the assertion beside it. Both of you can get the same answer. The difference shows up again on later turns, when the earlier log is still part of your conversation.
A token is a unit the model uses to represent text or other input. A short English word may be one token. Identifiers, punctuation and other languages can split differently. You can count lines before sending a file. To learn how many tokens a particular Claude model processes, use its usage reporting or the API’s token counter. How Claude Code works · Claude API token counting
1. Read the right meter
Use a macOS, Linux or WSL terminal with Claude Code installed and signed in. Run claude in your shell, then enter /context and /usage inside Claude, closing each panel with Escape. Note the model and effort setting. Claude Code setup These readouts answer different questions.
| Question | Readout | What to look for |
|---|---|---|
| What is taking up room right now? | /context | Conversation history, files or tool results, instructions and tool definitions. A large starting footprint points to configuration. |
| How much work did this session consume? | /usage | Session usage by model where shown. Track uncached input, cache writes, cache reads and output separately. |
| Am I approaching my subscription limit? | Plan section of /usage | Usage for the plan’s time windows. A session’s estimated API price is separate from a subscription bill. |
| What was actually billed to an API account? | The provider’s billing console | Use the billing record for charges. Claude Code’s displayed cost is an estimate. |
The context window is how much a model can consider in one request. Session usage accumulates across requests. Ten turns can reuse the same long conversation many times, so cumulative input can exceed the window size. Output tokens cover everything the model generates, including its thinking and tool calls. A short visible reply alone does not measure the cost of reaching it. Claude Code usage and costs · Interactive commands
“Read the logs and explain everything that went wrong” leaves the search open-ended. Try “Identify the failing test. Quote its expected and actual values. Use the supplied excerpt first. If the cause is unclear, name the next file you would need. Stop after three bullets.” You have specified the evidence, the deliverable and a stopping point. For code changes, include the acceptance check too, such as a particular regression test.
2. Do the 1,000-line experiment
Start a new lab. Type /exit, check python3 --version in the shell, then run lab=$(mktemp -d "${TMPDIR:-/tmp}/claude-token-lab.XXXXXX") && cd "$lab" && pwd. Save the printed path. Resume the lab. Type cd followed by a space and your saved path in quotes. Skip the creation block if you already have the files. You can repeat either prompt directly using the saved log and excerpt.
Paste the whole block in the new lab. The Python program stands in for a build with a single failing test. The shell script runs the command you give it, saves both output streams and remembers its exit status before filtering. It shows the first failure and the following line. If there is no FAIL line, it shows the last five lines for a first look.
cat > sample-build.py <<'PY'
for line in range(1, 1001):
if line == 733:
print("FAIL test_proof_date")
elif line == 734:
print("expected 2026-11-15, received 2026-11-14")
else:
print(f"PASS check_{line:04d}")
raise SystemExit(1)
PY
cat > summarize-build.sh <<'SH'
status=0
"$@" > build.log 2>&1 || status=$?
grep -m 1 -A 1 '^FAIL ' build.log > failure.txt || tail -n 5 build.log > failure.txt
cat failure.txt
exit "$status"
SH
sh summarize-build.sh python3 sample-build.py
echo "Build exit = $?"
wc -lc build.log failure.txt
Expect FAIL test_proof_date, then expected 2026-11-15, received 2026-11-14, then Build exit = 1. The nonzero status is intentional. The full log has 1,000 lines and 16,030 bytes. The excerpt has 2 lines and 62 bytes. Those lines establish a one-day difference. Diagnosing its cause needs more evidence. The measured sizes are bytes. Token counts depend on the model and the rest of the request.
In the lab shell, start claude. For run A, paste this entire line into Claude. The @ reference asks Claude Code to include the file. Wait for the answer, then record /usage before leaving the session.
@build.log Name the failing test and its expected and received values. Use only the supplied text. Answer in one sentence.
Close the usage panel, type /exit, then start claude again from the same folder. Run B with exactly the same prompt, replacing only @build.log with @failure.txt. Keep the model and effort fixed. If your client skips a file (for example, because a global ignore rule hides logs), paste each file’s literal contents instead and restart both trials. In both answers look for test_proof_date, expected 2026-11-15, received 2026-11-14.
Record each answer, tool calls, retries, the model, effort and cache state. In /usage, capture uncached input, cache writes, cache reads and output where available. Add uncached input, cache writes and cache reads to get the total input each run processed. With caching, the uncached figure counts only the end of a request, so it can be the same in both runs while the attached file shows up in cache writes and cache reads. With nothing else changed, run A’s total should be the larger one. If your client shows only plan-level figures, use the evidence-size comparison above. A percentage change in a plan window cannot price these two prompts. API users can compare estimated input with the token-counting endpoint. If you measure costs across multiple trials, alternate the order. Divide total cost, including failed attempts, by the number of correct answers for each variant. Report zero successes separately. Token counting · Reading session usage · Total input with caching
3. Keep tool output out of the conversation until it earns its place
When you need one error, filter a file locally and return that error with its surrounding lines. When you need a list of changed files, start with git diff --stat. Ask for the full diff of the relevant file only after you identify it. Large generated files, dependency lockfiles, screenshots and copied web pages can be expensive inputs. They belong in the session when their details bear on the question.
Use the wrapper from step 2 with your own test command in a scratch folder. Each run replaces build.log and failure.txt, so save any earlier evidence you need first. A pipeline ending in tail can report success after a failed build. The wrapper returns the build’s status. Remove credentials and customer data before sharing an excerpt.
Filter at the command when you need to keep a failed build’s full output out of the conversation. A PostToolUse hook that adds a summary leaves the original result in context. For successful calls it can replace the result with a correctly shaped updatedToolOutput. A PostToolUseFailure hook cannot rewrite the failure output. A prompt or agent hook also consumes a model turn. Hook output rules · Processing output with hooks and skills
4. Put instructions where they will be needed
Keep the essential project contract in CLAUDE.md. A build command, a non-obvious directory boundary and a required acceptance check can prevent costly mistakes. A detailed quarterly release procedure has a different audience. Put the procedure in a skill or referenced file that Claude opens when doing a release. A normal discoverable skill has a description available up front, and its full body loads when invoked. A manual-only skill can use disable-model-invocation: true. How skills load
Apply the same reasoning to tools. Inspect /context and /mcp for integrations you rarely use. Tool search can defer tool definitions, so the number of installed tools alone is a poor measure of overhead. Disable an unused integration for a trial, measure the starting footprint again, and keep required team checks enabled. The runtime cost of a plugin depends on what it loads, what it runs, and how much output reaches Claude. Reducing MCP overhead
5. Decide what the next turn needs to remember
| Situation | Action | What to preserve |
|---|---|---|
| Same bug, same files, useful history | Continue the session | The relevant test, observed error and last attempt. |
| Same job, long investigation, little room left | /compact Keep the failing test, the two date values and the next experiment. | Check the summary against the original evidence. Compaction itself uses a request. |
| A different job begins | Save a short handoff if needed, then /clear | File paths, decisions, unresolved question and the command to reproduce. |
| A verbose investigation can be isolated | Give one subagent a bounded question and request the evidence back | The main chat receives a short result. Count the subagent’s usage in the total. |
Clearing early can make Claude rediscover everything it just learned. Compacting after every turn spends tokens writing summaries and may discard a detail you need. A good time to decide is when you can say what the next action depends on. Context management
6. Treat caching, model choice and token reduction as separate levers
Prompt caching can reuse a matching prefix of a request. Imagine the same style guide followed by a different paragraph in each request. Keeping the stable guide first makes an exact prefix match possible. The paragraph changes at the end. Cache reads can cost less and reduce latency, while the guide still occupies context. Cache creation, expiry and a change near the start affect the economics. Claude Code manages its own caching. In a direct API integration, use Anthropic’s cache controls and inspect the cache fields in the response. Claude Code prompt caching · API prompt caching
Model choice changes the price and capability of each attempt. Try a lower-cost model for classifying clearly labeled failures. Keep a stronger one for a diagnosis that crosses code, timestamps and test data. Use /model to see what your account offers. Effort controls how much reasoning a supported model can spend. Try a lower /effort for a mechanical transformation, then check the output on a hard example before making it the default. If retries erase the saving, restore the previous setting. Model and effort controls
A direct API caller can also set a maximum output length. Pick a ceiling that leaves room for a complete answer and check the response’s stop reason. A truncated answer that has to be regenerated can cost more than a slightly longer first response. In Claude Code, ask for the format the reader needs, such as one diagnosis, one supporting line and one next check. Messages API response fields



