DEV Community: Paul Irolla

Claude Code /compact: What It Costs and What Survives

Paul Irolla — Mon, 26 Oct 2026 05:29:37 +0000

The same /compact can cost you a few cents or a couple of dollars, and the context size does not decide which. The cache does. Anthropic's own prompt caching documentation for Claude Code says it plainly: to write the summary, Claude Code sends a separate request carrying your whole history, and "while the cache is warm, that request reads your prefix from the cache, so a mid-session /compact costs a fraction of what the context size suggests". After a break longer than the cache lifetime, the same request "reprocesses the full history as uncached input". That is why /compact costs the most right after you resume an old session.

Most guides on Claude Code compaction stop at "it summarizes your conversation" and a rule of thumb for when to run it. This one puts the cost mechanics beside the survival rules, and names the alternatives, so you can tell which move is cheap at the moment you are about to make it.

TL;DR

/compact sends one extra request containing your full conversation plus a summarization instruction. While the prompt cache is warm it reads that history at cache price; once the cache has expired it pays full input price.
The turn after compaction is cheap: it only rebuilds the cache for the short summary.
CLAUDE.md, auto memory, the plan and a fresh git status come back from disk. Path-scoped rules, nested CLAUDE.md files and anything a hook injected earlier are summarized away.
Auto-compact fires near the model's limit: around 967K tokens on 1M-window models, at 200K on 200K-window setups. /autocompact moves that point.
/clear costs nothing, /rewind reuses a cache that already exists, and /recap summarizes without touching the cache. Pick /compact when you need continuity and the cache is still warm.

What /compact actually does

Compaction replaces your message history with a summary written by the model. Anthropic's session management post (Thariq Shihipar, April 15, 2026) describes it as "lossy, but you didn't have to write anything yourself", and you can steer it with instructions such as /compact focus on the auth refactor, drop the test debugging.

Mechanically, the prompt caching page lists four steps:

Claude Code sends a separate request with the same system prompt, tools and history as your conversation, with the summarization instruction appended as a final user message.
The model writes the summary. As of v2.1.198 that request inherits your session's extended thinking setting, according to the context window page.
Claude Code swaps the history for the summary and reloads project context (CLAUDE.md, memory) from disk.
Your next turn builds a new cache entry for the shorter history.

Two consequences follow. First, compaction invalidates the conversation layer of the cache by design, because the new history shares no prefix with the old one. The system prompt layer survives. Second, because CLAUDE.md is reloaded from disk, any edit you made to it mid-session takes effect at that point: the docs note that CLAUDE.md is "read once at session start" and that a new version "loads on the next /clear, /compact, or restart". If you edited CLAUDE.md since the session started, that reload is a cache miss on the project-context layer too.

In a fresh session, /compact does nothing useful. The costs page says it prints Not enough messages to compact. when there is no history to summarize.

If you want the broader picture of why every turn re-sends the whole conversation, our explainer on how the context window drives your token bill covers the base mechanism this section builds on.

What compaction costs: warm cache vs cold cache

The number that matters is not your context size. It is whether the cached prefix is still alive when the summarization request goes out.

Cache lifetime depends on how you pay. The TTL table in the Claude Code docs splits requests into two buckets:

Request bucket	Claude subscription, within plan usage	Usage credits, API key, or cloud provider
Main conversation	One hour	Five minutes
Everything else (subagents, forks, compaction, titles)	Five minutes, except some server-controlled helpers	Five minutes

Compaction sits in the second bucket, but the docs specify that the summarization call uses the same prefix-sharing approach as subagents, so it reads the cache your main conversation built. What decides whether that cache exists is how long you have been idle: under an hour on a subscription, under five minutes on an API key.

Here is what that means in dollars, using Anthropic's published prompt caching prices for Claude Opus 5.5 as of October 1, 2026: $4 per million input tokens, $0.20 per million for cache hits, $5 and $8 per million for 5-minute and 1-hour cache writes. This is arithmetic on list prices, not a measured bill, and it leaves out the output tokens of the summary itself.

400K tokens of history, warm cache: 400,000 × $0.20 / 1M = $0.08 of input for the summarization request.
400K tokens of history, cold cache: 400,000 × $4 / 1M = $1.60 of input, twenty times more for the same command.

On Sonnet 5.5 ($2 input, $0.20 cache hit per million on the same page), the same cold compaction costs $0.80 of input and the warm one stays at $0.08. The gap between warm and cold is a ratio of input price to cache-hit price, so it widens on the more expensive models.

On a Pro or Max plan you do not see dollars, but the same tokens count against your limits. The costs page lists compaction among the reasons usage climbs in a long session: "/compact reads the conversation it summarizes, so compacting a large context is itself a large request." For the plan side of this, see how Claude usage limits work.

The practical rule that falls out: compact while you are still working, not after lunch. If you come back to a large session after the cache has expired, Claude Code on Pro or Max offers to resume from a summary, which is the same trade made at the cheapest available moment.

What survives compaction, and what quietly disappears

The context window documentation gives a per-mechanism table. Condensed:

Kept or restored	Lost into the summary
System prompt and output style	Path-scoped rules (`paths:` frontmatter) until a matching file is read again
Project-root CLAUDE.md and unscoped rules, re-read from disk	Nested CLAUDE.md files in subdirectories, same condition
Auto memory, re-read from disk	Context that hooks injected earlier
The plan written in plan mode, re-read from disk	Everything else in the conversation not captured by the summary
A fresh git status snapshot
Up to five recently modified files Claude read or edited
Invoked skill bodies, capped at 5,000 tokens each and 25,000 in total

Three details in that table cause most of the "Claude forgot X after compaction" reports.

Files over 5,000 tokens come back as a path only. Claude Code re-reads up to five files, most recently modified first, but a large file returns as Referenced file without its content. If the model needs that file, it reads it again, and you pay for the read again. Our guide to skeleton compression for file reads covers ways to make those re-reads smaller.

Skills get truncated from the bottom. Truncation keeps the start of SKILL.md, and the oldest invoked skills drop first once the 25,000-token budget is exceeded. The docs advise putting the most important instructions near the top of the file. More on what skills cost in context in Claude Code skills: what they are, what they cost.

Rules scoped to paths vanish until triggered again. A rule with paths: frontmatter loads into message history when its trigger file is read, so compaction summarizes it away. If a rule must hold for the whole session, the docs say to drop the paths: frontmatter or move it to the project-root CLAUDE.md. That moves its tokens into every turn, so it is a trade worth making only for rules that matter. How a bloated CLAUDE.md inflates your bill shows what that trade costs.

When auto-compact fires

Auto-compact is the same pass as /compact, triggered for you. The model configuration page lists the defaults:

Models running with a native 1M window compact "at about 967K tokens by default". On the Anthropic API that covers Sonnet 5, the Fable models and Opus 4.7 and later.
Sonnet 4.6 and Opus 4.6 without extended context compact at the 200K boundary, as do Opus 4.8 and later when they run with a 200K window on Bedrock, Google Cloud or Foundry.
Setting CLAUDE_CODE_DISABLE_1M_CONTEXT=1 holds 1M models to 200K, and they compact there.
An unrecognized model ID, such as a gateway alias, compacts at the window Claude Code assumes for it.

You can move the trigger with /autocompact 500k (saved to your user settings as autoCompactWindow), with the --autocompact flag for a single launch, or with the CLAUDE_CODE_AUTO_COMPACT_WINDOW environment variable, which overrides both. The command and flag accept 100K to 1M tokens.

Waiting for the default has a quality cost on top of the token cost. The Anthropic post on session management puts it this way: "due to context rot, the model is at its least intelligent point when compacting." It also explains bad compactions: they happen "when the model can't predict the direction your work is going", for example when a long debugging session gets summarized and your next message asks about a warning the summary dropped. Our glossary entry on context rot covers the underlying effect.

There is also a timing cost. Auto-compact fires mid-task, wherever the threshold falls. The prompt caching page recommends running /compact "at a natural break in your work, such as between tasks, instead of waiting for auto-compaction to trigger mid-task", so you choose when the overhead lands.

/compact, /clear, /rewind, /recap: which one, when

Four commands shrink or reshape what the model sees. They differ in cost and in what they keep.

/clear starts a new conversation. The costs page is direct: "When you want a fresh start instead of continuity, /clear costs nothing." The price is effort: you write the brief yourself ("we're refactoring the auth middleware, the constraint is X, the files that matter are A and B"), and the model starts from what you decided was relevant. Anthropic's rule of thumb is that a new task deserves a new session.

/rewind (double Esc) truncates back to an earlier turn. Because "the remaining history is the same content the cache was built from at that point", the next request hits the earlier cache entry. Use it when Claude went down a wrong path: keep the useful file reads, drop the failed attempt, re-prompt with what you learned. /rewind also offers "Summarize from here" and "Summarize up to here" to compact part of the conversation.

/recap generates a summary for display in your terminal. Unlike /compact, it appends the summary as command output rather than replacing your history, so the cached prefix stays intact. It reorients you; it does not free any context.

/compact keeps continuity without you writing anything. It is the right call mid-task when the session is full of stale exploration you will not need again, and the cache is still warm.

A fifth option prevents the problem: send work that produces a lot of throwaway output to a subagent, so the file reads stay in its context window and only the result comes back. Anthropic's test is "will I need this tool output again, or just the conclusion?" Subagents have their own startup cost; measuring AI agent token usage explains how to check whether delegation paid off in your session.

Steering what the summary keeps

You have three levers on the summary's content, all documented.

Instructions on the command line. /compact Focus on code samples and API usage tells Claude what to preserve. The costs page uses this exact example.

A standing section in CLAUDE.md. The same page shows a # Compact instructions heading in the project-root CLAUDE.md, for example "When you are using compact, please focus on test output and code changes". Since project-root CLAUDE.md is re-injected after every compaction, these instructions stay available for every summary.

A SessionStart hook on the compact source. The hooks guide shows a SessionStart hook with "matcher": "compact" whose stdout is added to the compacted context:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "git log --oneline -5"
          }
        ]
      }
    ]
  }
}

The guide suggests git log --oneline -5 as a dynamic replacement for a static echo. Whatever this hook prints, you pay for it on every turn until the next compaction, so keep it short. PreCompact and PostCompact hooks also exist, with manual and auto matchers, if you want to log or react to each compaction. Hooks are one of several levers listed in our guide to reducing Claude Code token usage.

Measuring what compaction did to your session

Claude Code reports cache behaviour directly. Since v2.1.251, /usage adds a Prompt cache (main) line with the request count, the share of input served from cache, misses, and "expected rebuilds", which the costs page defines as misses caused by Claude Code itself rewriting the conversation "by compaction or by clearing old tool results". The example line in the docs reads 1 expected rebuild (compaction or tool-result clearing).

On a Pro, Max, Team or Enterprise plan, the /usage breakdown also flags behaviours such as long context or cache misses when one accounts for 10% or more of recent usage. If compaction keeps showing up there, the fix is usually timing (compact earlier, while warm) or scope (clear between tasks).

/context gives a live breakdown of what fills the window by category, including which CLAUDE.md and memory files loaded, per the context window page. Run it before and after a compaction to see what came back. For a tool-independent way to count tokens across sessions, see how to measure AI agent token usage and our Claude Code token usage statistics.

Common mistakes

Compacting right after resuming an old session. The cache has expired, so the summarization request pays full input on the whole history. Use the "resume from a summary" offer on Pro or Max, or /clear with a short brief.
Using /compact to switch tasks. You pay for a summary of work you no longer need, and the summary carries it into the new task. /clear is free and cleaner.
Correcting a failed attempt instead of rewinding. "That didn't work, try X" keeps the failed attempt in context. /rewind drops it and hits a cache that already exists.
Relying on path-scoped rules across a long session. They disappear at compaction until a matching file is read again. Move critical ones to the project-root CLAUDE.md.
Burying key instructions at the bottom of a skill. Re-injected skills are truncated from the end once they pass 5,000 tokens.
Letting auto-compact pick the moment. It fires mid-task, when context rot is at its worst, and summarizes without knowing where you are going next.

What to do this week

Add a # Compact instructions section to your project-root CLAUDE.md. Two lines naming what the summary must keep in this repo (test output, the files under active change). Expected result: fewer "it forgot X" moments after auto-compact, at a few dozen tokens per turn.
Lower your auto-compact window if you work on a 1M model. /autocompact 500k is the example the docs use. Expected result: compaction runs earlier, on a smaller and less rotted context, so the summarization request is cheaper and better.
Run /usage at the end of a long session. Look at the Prompt cache (main) line: misses versus expected rebuilds. If misses dominate, the cache is expiring between your turns; compact before breaks, not after.
Make /clear your default between tasks. Keep /compact for mid-task cleanup while the cache is warm, and /rewind for dead ends.

FAQ

What does /compact do in Claude Code? It replaces your conversation history with a summary the model writes. Claude Code sends a separate request with your full history and a summarization instruction, swaps the history for the result, then reloads CLAUDE.md, auto memory, the plan and a fresh git status from disk. Up to five recently modified files are re-read, and invoked skills are re-injected within a 5,000-token-per-skill and 25,000-token total budget, per the context window docs.

Does /compact cost tokens? Yes. The summarization request carries your whole conversation. While the cache is warm it reads that history at cache-hit price, which on Opus 5.5 is $0.20 per million tokens against $4 for uncached input (pricing as of October 1, 2026). After the cache expires, it pays full input price on the whole history. The summary's output tokens come on top.

Is /clear cheaper than /compact? Yes. The costs page states that /clear costs nothing. The trade-off is continuity: you write the brief for the next session yourself, while /compact writes it for you. For unrelated work, /clear is the better choice on both cost and quality.

When does auto-compact trigger? On models with a native 1M window, at about 967K tokens by default. On 200K-window setups, at the 200K boundary. An unrecognized model ID compacts at the window Claude Code assumes for it. You can change the point with /autocompact, the --autocompact flag or CLAUDE_CODE_AUTO_COMPACT_WINDOW, between 100K and 1M tokens (model configuration docs).

Why did Claude forget something after compaction? Either the summary dropped it, or it came from a mechanism that does not survive: path-scoped rules, nested CLAUDE.md files, context injected by hooks, or the content of a file over 5,000 tokens. Anthropic notes that bad compactions happen when the model cannot predict where the work is going, so passing instructions to /compact helps.

Does editing CLAUDE.md mid-session take effect after /compact? Yes. Project-root and user-level CLAUDE.md files are read once at session start and held in memory; a new version loads on the next /clear, /compact or restart, according to the prompt caching docs.

Can I keep important context across compactions? Put it in the project-root CLAUDE.md (re-read from disk every time), in a # Compact instructions section, or in a SessionStart hook with the compact matcher, whose output is added after each compaction. Each of these adds tokens to every turn, so keep them short.

What is the difference between /compact and /recap? /compact replaces your history with a summary and frees context. /recap prints a summary in your terminal and appends it as command output, leaving the history and the cached prefix untouched. Use /recap to reorient, /compact to make room.

Claude Code Hooks: Which Ones Add Tokens, Which Cut Them

Paul Irolla — Mon, 26 Oct 2026 01:00:05 +0000

The Claude Code hooks reference now lists 33 events, from SessionStart to ElicitationResult (Anthropic hooks reference, read 2026-09-24). Most people meet hooks through a list of ten copy-paste examples: a linter after every edit, a desktop ping, a guard on rm -rf. Then they read that a hook cut someone's token usage by 42% or 90% and wonder whether their own hooks help or hurt. Both happen. A hook that prints to stdout on UserPromptSubmit adds its text to the conversation on every prompt you send. A hook that rewrites a tool call before it runs can stop a 3,000-line log from ever reaching the model. The difference sits in two details the example lists skip: which event the hook listens to, and which JSON field it returns. This article maps every token-relevant event to what it adds or removes, using only the official reference, and lists the traps that leave a hook silently doing nothing.

TL;DR

Four events add plain stdout to Claude's context: UserPromptSubmit, UserPromptExpansion, SessionStart and PostModelSwitch. On every other event, stdout from a successful hook goes to the debug log and costs nothing.
additionalContext is a token cost by design: Claude Code wraps it in a system reminder and inserts it where the hook fired, and it stays in the conversation after that.
Two fields remove tokens: updatedInput on PreToolUse (rewrite the call before it runs) and updatedToolOutput on PostToolUse (replace the result before Claude reads it).
Every injected string is capped at 10,000 characters; past that, Claude gets a file path and a 2,000-character preview.
Exit 1 does not block, a timed-out PreToolUse hook lets the call through, and a mistyped script path disables a gate without stopping anything.

What a hook is, in cost terms

A hook is a handler that Claude Code runs at a fixed point of a session: a shell command, an HTTP endpoint, a tool on a connected MCP server, an LLM prompt or a subagent (reference). The reference groups the events by cadence. SessionStart and SessionEnd fire once per session. UserPromptSubmit, Stop and StopFailure fire once per turn. PreToolUse and PostToolUse fire on every tool call inside the agentic loop, so their count grows with every file read, search and command the agent runs.

That cadence is the first half of the cost question. A handler that fires once per session and injects 400 characters costs you those characters once, plus their re-reading on each later request. The same 400 characters on PreToolUse land next to every tool result in the session. Anything that enters the conversation is re-sent with the rest of the history on each following model request, which is why prompt caching matters so much for agents: cached re-reads are cheaper than fresh input, but they are never free.

The second half is what the handler returns. A hook can do four things with tokens:

Nothing. It runs, exits 0, and its stdout goes to the debug log. Most formatting, notification and logging hooks live here, and they have zero token cost.
Add context: plain stdout on the four events that accept it, or additionalContext in JSON.
Remove context before it exists: rewrite a tool's arguments with updatedInput, or replace its result with updatedToolOutput.
Call a model: prompt-based and agent-based hooks send the hook input to Claude, which is a separate billed request.

The rest of this article sorts the events into those four buckets. If you have never measured where your session's tokens go, do that first; measuring agent token usage shows how to read the usage fields in the session transcript.

The hooks that add tokens

Claude Code's rule for plain stdout is short. On exit 0, "for most events, Claude Code writes stdout to the debug log and doesn't show it in the transcript. The exceptions are UserPromptSubmit, UserPromptExpansion, SessionStart, and PostModelSwitch, where Claude Code adds plain-text stdout as context that Claude can see and act on" (reference, exit code 0).

So an echo in a SessionStart hook is a small, one-time addition. The same echo in a UserPromptSubmit hook is an addition on every prompt. The reference also notes that neither plain stdout nor additionalContext on UserPromptSubmit produces a visible transcript entry: each is injected as a system reminder that starts with the hook's name. You pay for text you never see on screen, which is the most common way a hook setup grows a bill without anyone noticing.

additionalContext is the structured version, and it works on more events. For PreToolUse and PostToolUse it is a "string added to Claude's context alongside the tool result." For SessionStart it is added "at the start of the conversation, before the first prompt." For SubagentStart and PostModelSwitch it is the only thing the hook can do: context, with no blocking (reference, decision control). When several hooks return additionalContext for the same event, Claude receives all of the values.

A third path is less obvious. On PostToolUse and PostToolUseFailure, exiting 2 "shows stderr to Claude; the tool already ran." The reference recommends it as the way to surface a warning from those events. Every warning is text in the conversation, so a linter hook that exits 2 with 80 lines of findings on each edit adds 80 lines per edit.

Stop hooks cost differently. Exit 2 on Stop "prevents Claude from stopping, continues the conversation." That is a whole new model turn, with the full history re-sent. A check that fails on every turn keeps the session going until you intervene. The prompt-based variant has a guard for that: when the model returns impossible with ok: false, Claude Code lets the turn end instead of feeding the reason back. Command hooks have no such guard; the loop is yours to bound.

The pattern to keep: context injection is fine when the text is short, changes the model's next move, and fires at the lowest cadence that still does the job. A branch name and the open issue at SessionStart pass that test. A 2,000-character style guide on every UserPromptSubmit belongs in CLAUDE.md, where it is at least part of the cached prefix.

The hooks that cut tokens

Two fields let a hook shrink what the model reads, and they act at opposite ends of a tool call.

updatedInput on PreToolUse "modifies the tool's input parameters before execution. Replaces the entire input object, so include unchanged fields alongside modified ones" (reference, PreToolUse decision control). This is where most token-saving hooks work. A Bash call to npm test can be rewritten to pipe through a filter that keeps failures only; a Read of a 5,000-line file can be narrowed with offset and limit; a Grep without a path can be scoped to src/. The model only ever reads the trimmed result, and nothing extra enters the context. Two details from the reference matter here. Permission rules are evaluated "against the input your hook returns, not the input Claude sent," so a rewrite cannot smuggle a command past a deny rule. And the replacement is whole-object: forget a field and the tool runs without it.

updatedToolOutput on PostToolUse "replaces the tool's output with the provided value before it is sent to Claude. The value must match the tool's output shape." The reference now recommends it over the older updatedMCPToolOutput, which works on MCP tools only. This is the field to use when you cannot know in advance how large a result will be: let the call run, then keep the error lines of a build log, drop the progress bars, or cut a JSON response down to the keys the model needs. The reference example replaces a Bash result's stdout with a redacted string, which shows the shape.

Note what decision: "block" on PostToolUse does and does not do: it "adds the reason next to the tool result. Claude still sees the original output; to replace it, use updatedToolOutput." A blocking PostToolUse hook meant to hide a huge output adds text and removes nothing.

The published results for this approach are single-team benchmarks, so read them as orders of magnitude. SitePoint reported on 2026-08-20 that Graft, a hook-based framework, cut mean token usage from 8,070 to 4,650 per task on its authors' internal SWE-bench Verified runs, a 42% drop (SitePoint). Spotify Engineering published an engineer's account in September 2026 titled "Portal by Spotify cut my Claude Code token usage by 90%," which argues that most of what a coding agent does is I/O, such as reading five files to answer a question about one method (Spotify Engineering). Neither is a controlled test on your repository. The mechanism behind both is the one described above, and the general technique has its own page: output filtering for command logs.

The 10,000-character ceiling

Every string a hook injects has a hard limit. The reference: "A hook's additionalContext, systemMessage, and initialUserMessage strings, and its plain stdout, are capped at 10,000 characters." Each JSON field is measured separately, plain stdout is measured whole, and several hooks on one event are each measured on their own (reference, JSON output).

Over the limit, Claude Code does not truncate. It "saves the output to a file in the session directory and replaces it with the file path and a preview of up to the first 2,000 characters." Claude can read that file, but Claude Code doesn't ask it to. Large valid Bash results are handled the same way. Unlike the Bash ceiling, the hook cap "has no setting or environment variable to raise it."

Two consequences for cost:

The cap is a ceiling per string, and nothing stops you from sending 9,999 characters on every prompt. It protects against runaway hooks, and a hook that stays under it can still be the largest single item in your context.
Crossing the cap can make things worse. If the model decides it needs the full text, it reads the file with a tool call, and you pay for the preview, the tool call and the full content.

If a hook regularly produces more than a few hundred characters, the better design is usually to write the details to a file yourself and inject one line pointing to it.

Hooks that call a model

Prompt-based hooks (type: "prompt") "send the hook input and your prompt to a Claude model, Haiku by default"; the model field overrides it (reference, prompt-based hooks). Agent-based hooks go further and run a subagent that can use tools before deciding. Both are billed requests on top of your main session.

That changes the arithmetic for high-cadence events. A prompt hook on Stop runs once per turn, which is usually tolerable. A prompt hook on PreToolUse runs a model request for every tool call, and each one carries the hook input, including the full tool arguments. For a check that a regular expression or jq can do, a command hook costs nothing in tokens and answers in milliseconds.

Use prompt and agent hooks where judgment is the point: deciding whether a task is really finished before letting Claude stop, or whether a diff touches something a rule forbids. Keep them off the per-tool-call path unless you have measured the extra requests. Agentic coding costs follow the same logic: every fresh model context starts with its own overhead.

PreModelSwitch: the first native cost signal in a hook

For a long time, the complaint in GitHub issue #11008, opened in November 2025, held: hooks received no token or cost data, so a budget hook had to parse the transcript itself. PreModelSwitch changes that for one expensive moment. Its input includes context_tokens (the tokens the next request re-sends as its prompt), prompt_cache_warm, cache_ttl, and estimated_cache_write_usd, the estimated cost of writing that context to the new model's cache (reference, PreModelSwitch input).

Why it matters: a model switch forfeits a warm prompt cache. The reference's own example shows a /model opus request from a Sonnet 5 session with 182,340 context tokens and an estimated cache write of $1.14 at list price. A hook can return permissionDecision: "ask" with that figure in the reason, so the switch happens with the price in front of you. The default timeout for this event is 30 seconds, and unlike PreToolUse, a PreModelSwitch hook that times out blocks the switch.

For every other event, the transcript remains the source. Each hook receives transcript_path, and the reference warns that the file "is written asynchronously and may lag the in-memory conversation." A cost hook reading it should expect the latest turn to be missing. For per-session numbers without writing a hook, see how to reduce Claude Code token usage, which covers the existing counters.

Common mistakes

Using exit 1 to block. "Without valid JSON on stdout, Claude Code treats exit code 1 as a non-blocking error and proceeds with the action." Policy hooks must exit 2, or return a JSON decision.
Trusting a slow gate. A command, http or mcp_tool hook on PreToolUse that reaches its timeout "doesn't block the tool call." If your filter shells out to something slow, the unfiltered call goes through.
A typo in the script path. The shell exits 127, Claude Code shows a non-blocking notice, and "a mistyped path in settings.json leaves the gate silently disabled." Watch the first run.
Matching MCP tools with a bare prefix. mcp__memory is compared as an exact string and matches no tool; mcp__memory__.* matches all of that server's tools.
Printing a banner from the shell profile. Stdout must contain only the JSON object. A profile that echoes on startup breaks parsing, and the JSON fields are ignored.
Expecting suppressOutput to save anything. The reference says it "has no effect": Claude Code accepts the field and does not act on it. Successful hook stdout already stays out of the transcript on most events.

What to do this week

List your hooks by event. Open /hooks and write down every handler on UserPromptSubmit, SessionStart, PreToolUse and PostToolUse. For each, note whether it prints plain stdout, returns additionalContext, or exits 2 with stderr. Those are your token-adding hooks.
Move per-prompt text to a lower cadence. Anything on UserPromptSubmit that does not change between prompts goes to SessionStart or to CLAUDE.md. Expected outcome: the same guidance, paid once instead of per prompt.
Add one output-shrinking hook to your noisiest tool. Check the transcript for the tool whose results are largest (usually Bash running tests or builds) and add a PostToolUse hook that returns updatedToolOutput with errors and the summary line only. Compare total input tokens over two similar sessions before and after.
Make every policy hook exit 2 and test it. Run one command it should block and confirm the block appears. A gate you have not seen fire is not a gate.
Add a PreModelSwitch hook with "ask". Quote context_tokens and estimated_cache_write_usd in the reason, so a mid-session model switch shows its price before it happens.

FAQ

What are Claude Code hooks? Hooks are handlers Claude Code runs automatically at fixed points of a session: before and after tool calls, when you submit a prompt, when a session starts or ends, before compaction, and about thirty other events. A handler can be a shell command, an HTTP endpoint, an MCP tool, an LLM prompt or a subagent. It receives the event as JSON (on stdin for commands) and can return a decision, extra context, or a rewritten tool input or output. You configure them in settings files or through the /hooks menu.

Do Claude Code hooks use tokens? Only when their output enters the conversation or when they call a model. On most events, stdout from a successful hook goes to the debug log and costs nothing. Plain stdout on UserPromptSubmit, UserPromptExpansion, SessionStart and PostModelSwitch is added to context, additionalContext is added wherever it is supported, and stderr from an exit-2 PostToolUse hook is shown to Claude. Prompt and agent hooks are separate model requests, Haiku by default for prompt hooks.

Can a hook reduce Claude Code token usage? Yes, through two fields. updatedInput on PreToolUse rewrites a tool call before it runs, for example narrowing a file read or piping a test command through a filter. updatedToolOutput on PostToolUse replaces a tool's result before Claude reads it. Published results come from single-team benchmarks: SitePoint reported a 42% drop per task for Graft on its authors' own SWE-bench runs in August 2026. Measure on your own sessions before trusting a figure.

What is the difference between PreToolUse and PostToolUse? PreToolUse fires before a tool call executes and can block it, ask for confirmation, or rewrite its arguments with updatedInput. PostToolUse fires after a call succeeds; it cannot undo the call, but it can add context, show a warning via exit 2, or replace the result with updatedToolOutput. For token savings, PreToolUse avoids producing a large output at all, and PostToolUse handles output whose size you cannot predict.

Why does my hook not block anything? The usual causes are exit code 1 instead of 2, a script path that does not exist, a matcher that matches no tool (an MCP prefix without .*), text printed before the JSON on stdout, or a PreToolUse hook that timed out. The reference is explicit that a timed-out command hook on PreToolUse lets the tool call continue. Enable debug logging to see the parse or validation message, and test each gate with a call it should stop.

Is there a size limit on hook output? Yes. additionalContext, systemMessage, initialUserMessage and plain stdout are each capped at 10,000 characters. Above that, Claude Code writes the text to a file in the session directory and gives Claude the path plus a preview of up to 2,000 characters. No setting or environment variable raises this cap. The notes a hook attaches for the auto mode classifier have a separate 2,000-character cap per tool call.

Can a hook see how many tokens the session has used? Not directly on most events: GitHub issue #11008 asked for token and cost data in hook inputs. Every hook receives transcript_path, and the transcript's usage fields can be summed, keeping in mind that the file is written asynchronously and may lag the latest turn. PreModelSwitch is the exception: its input carries context_tokens and estimated_cache_write_usd for the switch it is about to allow or block.

Should I use prompt-based hooks? Use them where a judgment call is the point, such as checking before Stop whether the task is really done. Avoid them on PreToolUse or PostToolUse unless you have measured the cost, because they add one model request per tool call. Anything a regular expression, jq or a short script can decide belongs in a command hook, which costs no tokens.

Claude Code Subagents Token Usage: What They Really Cost

Paul Irolla — Sun, 25 Oct 2026 01:00:06 +0000

Search "Claude Code subagents token usage" and the first page argues with itself. One writer cut their usage billing by 40% by sending grunt work to subagents. Another watched Claude Code spin up five subagents in parallel and hit the Pro limit in about 15 minutes. A third counted 66K to 84K tokens per subagent (July 18, 2026) before any code was written. All three can be right at once, because a subagent trades two costs against each other: a fixed startup bill it pays every time, and the context it keeps out of your main session. Which side wins depends on the task, and you can read both sides for your own sessions. In this article I show what a fresh subagent loads before it does anything, how to pull the real token count of each subagent out of the transcript files Claude Code already writes, and the rule I use to decide whether a task deserves one.

TL;DR

A non-fork subagent starts with an empty conversation but a full startup payload: its own system prompt, the task message, your CLAUDE.md hierarchy (Explore and Plan skip it), git status and any preloaded skills (Claude Code docs).
That payload is written to the prompt cache from scratch. On one of my sessions in September 2026, 19 subagents each wrote between 12,427 and 40,763 tokens on their first request, with zero cache read.
Per-subagent usage sits in ~/.claude/projects/<project>/<session>/subagents/agent-<id>.jsonl. Deduplicate by message ID before summing, or you will count the same request two or three times.
Delegate when the work would pour far more tokens into your main context than the startup bill, and the result comes back as a short summary. Keep small, sequential edits in the main session.
Forks (/subtask) reuse the parent's prompt cache, so they cost less to start than a fresh subagent for work that needs the same context.

What a subagent is, in token terms

The official definition is short. A subagent is "an isolated Claude instance with its own context window. It takes a task, does the work, and returns only the result," in Anthropic's guide to subagents (April 7, 2026). The same post is candid about the price: "subagents carry overhead. Each one spins up its own context, consumes tokens, and adds a layer of indirection between the developer and the work."

For your bill, three consequences follow from "own context window."

First, the subagent re-reads nothing from your conversation. The docs on what loads at startup say it "doesn't see your conversation history, the skills you've already invoked, or the files Claude has already read." Claude writes a delegation message that summarizes the task, and the subagent starts from there. If the answer depends on something you established twenty turns ago, the subagent will either miss it or go find it again, and finding it again costs tokens.

Second, everything the subagent reads stays in its own context. A grep that returns 3,000 lines, a test log, twelve files opened to find one function: the main session never sees them, only the summary. That is the saving people report, and it compounds, because every later turn of your main session re-sends the whole context window as input.

Third, the subagent is a separate agent loop with its own turns. Each of its tool calls sends its growing context back to the model, exactly like the main session does. A subagent that wanders through forty tool calls is a small long session of its own.

Anthropic's own numbers for multi-agent work set the scale. In its write-up of the Research multi-agent system (June 13, 2025), agents used about 4× more tokens than chat interactions and multi-agent systems about 15× more. The Claude Code cost docs give a similar warning for agent teams, which "use approximately 7x more tokens than standard sessions when teammates run in plan mode." Agent teams are a different, experimental feature from ordinary subagents, but the mechanism is the same: each instance keeps its own context.

The startup bill: what loads before the first tool call

The docs list what a non-fork subagent's initial context contains. Here is that list with the part that matters for cost:

Loaded at start	Size driver	Who skips it
System prompt	The agent's own prompt plus environment details Claude Code appends	Nobody
Task message	The delegation prompt Claude writes	Nobody
CLAUDE.md files	Every level the main session loads, including `~/.claude/CLAUDE.md` and project rules	Explore and Plan; any agent with `omitClaudeMd: true`
Git status	Snapshot taken at the start of the parent session	Explore and Plan
Preloaded skills	Full content of skills named in the agent's `skills` field	Built-in agents
Tool definitions	The tools the agent is allowed to use, MCP tools included	Restricted by `tools` / `disallowedTools`

Source: Create custom subagents, "What loads at startup", read September 17, 2026. The tool definitions row is my addition: they are part of every request to the model, so a subagent that inherits forty MCP tools carries their schemas too.

The line that surprises most people is CLAUDE.md. If your global and project CLAUDE.md files add up to 8,000 tokens, every general-purpose or custom subagent you spawn carries those 8,000 tokens on every one of its requests. Five parallel subagents carry them five times. The CLAUDE.md bloat problem gets multiplied by delegation.

The other thing that surprises people is caching. A fresh subagent has a different system prompt from your main session, so it cannot read the prompt cache your session has already warmed. Its first request writes its startup payload to the cache. Forks behave differently: the docs note that "because a fork's system prompt and tool definitions are identical to the parent, its first request reuses the parent's prompt cache," which "makes forking cheaper than spawning a fresh subagent for tasks that need the same context." If you want the mechanics of cache reads versus writes, the prompt caching glossary entry covers them, and how prompt caching cuts input cost shows the effect on a bill.

What I measured on my own sessions

Claude Code writes one transcript per subagent. The docs give the location: ~/.claude/projects/{project}/{sessionId}/subagents/, one agent-{agentId}.jsonl file per subagent. Each assistant message in those files carries a usage object with input_tokens, cache_creation_input_tokens, cache_read_input_tokens and output_tokens.

I opened the subagent transcripts of one Claude Code session on my machine in September 2026 (model claude-opus-5) and read the first request of each subagent. For the 19 subagents I checked:

every first request had cache_read_input_tokens at 0;
cache_creation_input_tokens on that first request ranged from 12,427 to 40,763;
the values fell into two groups, about 12,400 to 15,600 and about 37,000 to 40,800. I did not check which agent types sit in which group, so I will not claim a cause, though the CLAUDE.md row in the table above is the obvious suspect.

One long-running subagent in the same session also had a request deep into its run (line 481 of its transcript) that wrote 253,567 tokens to the cache with nothing read. I have not confirmed why the cache missed there. The lesson I take from it is narrower: a subagent that runs long enough can pay for its whole context a second time, and you will only see it if you look at the transcript.

This is one session on one machine, so read it as an order of magnitude, not a benchmark. It agrees with the direction of the public reports above: the startup bill of a fresh subagent is in the tens of thousands of tokens, before it reads a single file. The broader Claude Code token usage statistics page collects other published measurements.

How to measure the token cost of each subagent

In February 2026 a user opened a feature request for per-subagent token tracking, explaining that "there's no way to measure how many tokens each agent consumed." The issue was later closed as stale. You do not need the feature: the per-agent transcript files already hold the numbers.

There is one trap. Claude Code writes a streamed response as several lines, and those lines repeat the same message ID with the same usage object. In the transcript I checked, one request appeared on three separate lines with identical usage. Sum the lines naively and you triple-count. Deduplicate by message.id first.

With jq installed, this prints one line per subagent of a session:

for f in ~/.claude/projects/*/SESSION_ID/subagents/agent-*.jsonl; do
  jq -s -c --arg f "$(basename "$f")" '
    map(select(.message.usage)) | unique_by(.message.id) | map(.message.usage)
    | {agent: $f,
       requests: length,
       input: (map(.input_tokens) | add),
       cache_write: (map(.cache_creation_input_tokens) | add),
       cache_read: (map(.cache_read_input_tokens) | add),
       output: (map(.output_tokens) | add)}' "$f"
done

Replace SESSION_ID with the session you want (the folder names under your project are session IDs). Read the output with three questions:

Is cache_write on the first request close to the total cache_write? Then most of what you paid was startup, and the task was probably too small to delegate.
Is requests high? Forty requests means forty round trips, each re-sending the subagent's context. A tighter delegation prompt or a maxTurns limit helps.
Is one agent far above its siblings? That is the one to open. Usually it went exploring outside the scope you gave it.

For the session-level picture, /usage and the other tools in how to measure agent token usage remain the right starting point. The per-agent loop above answers the narrower question of which delegation was worth it.

On a subscription, these are not dollars but they still count: Pro and Max limits are consumed by subagent tokens like any others, which is how a parallel fan-out can end a five-hour window early. The Claude usage limits explainer covers how those windows work.

When a subagent saves tokens, and when it burns them

Anthropic's guide names the cases where delegation pays: research-heavy tasks, independent sub-tasks that can run in parallel, and reviews that should not inherit the main session's assumptions. It also says that "for smaller or tightly sequential tasks, sticking to the main conversation is usually simpler."

In token terms, the break-even is simple to state. A subagent saves tokens when:

(tokens the work would add to your main context) × (turns left in your main session) is larger than (startup bill) + (the subagent's own work) + (the summary it returns).

The first term is what makes the difference. Tokens that land in your main context are re-sent on every later turn. A 30,000-token log read at turn 10 of a 60-turn session gets processed again on each of the 50 remaining turns, mostly as cheap cache reads but never free, and it pushes the session toward compaction sooner. The same log read inside a subagent is paid once, inside a context that disappears when the subagent returns.

That gives a practical split.

Delegate:

Wide searches. "Find every place we call the payments client and tell me which ones pass a retry option." The raw search output is large, the answer is a list.
Log and test triage. "Run the suite and report only failing tests with their error messages," as the docs suggest. Test output is one of the largest sources of wasted context; output filtering is the other fix.
Independent parallel work across packages, when nothing depends on the order.
A clean-slate review before you commit, where not seeing your conversation is the point.

Keep in the main session:

Edits to one or two files you already have open. The subagent would re-read them.
Chains where step two depends on the detail of step one. The summary loses exactly the detail you need.
Questions about things already in your context. The docs point to /btw for this: it "sees your full context but has no tool access, and the answer isn't added to history."
Anything short. If the work itself is a few thousand tokens, the startup bill alone is larger.

Settings that shrink the bill

Once you know which subagents you keep, a few settings from the docs change what each one costs.

omitClaudeMd: true on custom agents. It launches the subagent without the user, project and local CLAUDE.md files (managed policy files still load). The docs point out that "the main conversation still has your full CLAUDE.md when it reads these subagents' results, so most rules don't need to reach the subagent itself." If a rule must reach it, write that rule into the delegation prompt. This setting requires Claude Code v2.1.271 or later.

A tight tools list. A read-only research agent does not need write tools or every MCP server. Fewer tools means smaller tool schemas on every request and fewer ways to wander. If MCP schemas are the bulk of your payload, lazy MCP loading addresses that at the source.

The model field. Accepted values are sonnet, opus, haiku, fable, a full model ID, or inherit. A search-and-summarize agent rarely needs the model you chose for the main session. Two caveats from the docs: a subagent's context window "is sized by its own model, not the parent's," and CLAUDE_CODE_SUBAGENT_MODEL can force one model onto every subagent, which overrides the per-agent choice.

maxTurns. It caps the agentic turns before the subagent stops and returns partial output. It is a blunt tool, but it turns a runaway exploration into a bounded one, and a resumable subagent can be told to continue.

Forks for context-heavy side tasks. When the side task needs what your session already knows, /subtask starts a fork that reuses the parent's cache instead of paying a fresh startup bill.

The concurrency ceiling. By default Claude Code refuses to spawn another subagent while 20 are running (CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS changes it). That is a safety limit, not a budget. If you run agents unattended, the controls in overnight agent budget safety matter more.

Common mistakes

Summing transcript lines without deduplicating. Streamed responses repeat the same usage on several lines. Per-agent totals come out two or three times too high, and the "subagents are expensive" conclusion gets exaggerated.
Delegating a task that needs the conversation. The subagent does not see your history. It either guesses or re-reads, and re-reading is the expensive path.
Heavy CLAUDE.md plus many custom agents. Every general-purpose or custom subagent carries the whole hierarchy. Trim CLAUDE.md or set omitClaudeMd on agents that get their instructions from the prompt.
Asking for "a full report." The return value lands in your main context. Ask for the list, the failing tests, the three files: the output format is part of the saving.
Judging from one anecdote. The 40% saving and the 15-minute Pro limit are both real reports from different workloads. Measure your own before changing your habits.
Assuming parallel means cheaper. Parallel subagents finish sooner. The token total is the sum of every agent's startup bill and work, whatever the wall-clock time.

What to do this week

Read one session's subagent bill. Pick a recent session where Claude Code delegated, run the jq loop above, and note the first-request cache_write for each agent. You need jq and five minutes. You will know your own startup bill instead of borrowing someone else's.
Find the delegations that did not pay. Any agent whose total cache_write is mostly its first request, with a handful of requests, did too little work to justify spawning. Write one line in your CLAUDE.md telling Claude which kinds of tasks to keep in the main session.
Trim what every subagent carries. Measure your CLAUDE.md files, then add omitClaudeMd: true and a narrow tools list to the custom agents that do search or triage. Re-run the loop on a comparable session and compare first-request cache_write.
Move one noisy job into a subagent on purpose. Test runs or wide searches are the usual candidates. Ask for a short, fixed output format and compare the main session's context before and after with /context.

FAQ

Do Claude Code subagents use more tokens than a single session?

In total, usually yes. Each fresh subagent pays a startup bill (system prompt, CLAUDE.md, git status, tool definitions) and runs its own loop. Anthropic measured multi-agent systems at about 15× the tokens of chat interactions in its Research system write-up. What subagents can reduce is the size of your main context, and with it the cost of every later turn. Whether the total goes down depends on how much raw material the subagent kept out of the main session and how many turns that session still had to run.

How many tokens does a subagent use just to start?

It depends on your CLAUDE.md files, the agent's prompt, its tools and preloaded skills. On one of my sessions in September 2026, 19 subagents each wrote between 12,427 and 40,763 tokens to the cache on their first request, with nothing read from cache. A public report from July 2026 measured 66K to 84K tokens per subagent over whole runs. Measure yours with the transcript loop in this article.

Do subagents load my CLAUDE.md?

General-purpose and custom subagents load every level of the CLAUDE.md hierarchy the main session loads, according to the subagent docs. The built-in Explore and Plan agents skip it. A custom agent with omitClaudeMd: true loads only managed policy files. If a rule must reach such an agent, put it in the delegation prompt.

How do I see token usage per subagent?

Claude Code stores one transcript per subagent at ~/.claude/projects/<project>/<session>/subagents/agent-<id>.jsonl. Each assistant message has a usage object. Deduplicate by message.id, because one streamed response appears on several lines, then sum input, cache write, cache read and output tokens. The jq loop above does it per agent.

Is the Explore subagent cheaper than general-purpose?

It starts lighter. Explore skips CLAUDE.md and git status and is limited to read-only tools. Its model inherits from the main conversation, capped at Opus on the Claude API, so it never runs on a more expensive model than the session. What it costs in total still depends on how much it searches. Explore is one-shot and cannot be resumed, so follow-up questions start a new instance and a new startup bill.

Are forks cheaper than subagents?

To start, yes, for work that needs the same context. A fork launched with /subtask inherits the parent conversation, and its first request reuses the parent's prompt cache because its system prompt and tool definitions are identical. A fresh subagent writes its own cache from scratch. The trade-off: a fork carries your whole conversation, so it is a poor choice when the side task needs none of it.

Why did parallel subagents burn through my Pro limit?

Subscription limits count every agent's tokens. Five parallel subagents pay five startup bills and run five loops at the same time, so usage arrives much faster than in a single session doing the same work sequentially. One developer reported hitting the Pro limit in about 15 minutes that way, against roughly 30 minutes of sequential processing. If limits matter more than wall-clock time, ask Claude to run the sub-tasks one after another.

Should I set subagents to a smaller model?

For search, triage and summarizing, often yes, through the model field of a custom agent. Keep two limits in mind: the subagent's context window is sized by its own model, and a smaller model that misreads the task can cost you a second delegation. Try it on one noisy agent, compare the transcript totals and the quality of the summaries, then decide.

I open-sourced Tokenade, my token optimizer for coding agents. Here is why the paid model did not hold

Paul Irolla — Mon, 19 Oct 2026 22:50:54 +0000

Tokenade is free and open source as of version 2.0, under MIT OR Apache-2.0. The code is on GitHub: https://github.com/pi-infected/tokenade

I tried to sell it first. Here is why that did not hold, what Tokenade does, and how to check it on your own sessions.

Why the paid model did not hold

Most people run Claude Code, Cursor or Codex on a subscription. They never see a token bill, so a tool that shrinks the bill solves a problem they do not feel. The people who do pay per token call the API directly, and for them the useful version is a proxy in front of the provider. I do not want to run a proxy business.

So the honest move was to give it away and let the code speak.

What it does

A coding agent pays for what it reads, and it reads the same things again with each turn: build logs, test output, whole files it opened once and kept in the history. Tokenade works on that layer, on your machine.

Command output. When the agent runs a noisy command, Tokenade compacts what comes back before the model reads it. tokenade raw <cmd> bypasses it when you want the full output.
Finding code without reading it. tokenade map, query <symbol>, skeleton <file> and semantic "<question>" give the agent the structure it needs instead of whole files.
Documents and pages. tokenade read turns a PDF, a spreadsheet or a long file into the text that matters. tokenade web and tokenade search do the same for web pages and search results.
API users. tokenade llm-proxy runs locally between the agent and the provider. It folds tool results already in the history and sends an identical tool output only once. Run it, or fork it.

tokenade install detects the agents already on the machine and wires itself in. There is nothing to configure.

The number

On THOL, a public benchmark of token-harness optimizers that I maintain, Tokenade reduces token costs by 39% on average on long sessions (over 200k tokens) with Claude Code, measured on 2026-09-14. That is an average, not a ceiling, and the raw runs are public: https://pi-infected.github.io/token-harness-optimizer-leaderboard/

Try it

npm install -g @tokenade/cli
tokenade install

After a long session, tokenade dashboard shows what it saved, graphed by token category and by model.

If it saves you nothing, I want to know why: open an issue with the command or the setup. If it helps, a star on the repo is the quickest way to tell me.

Anthropic admitted that Fable burned through their €200/month Claude Code plan in 1 hour instead of 5.

Paul Irolla — Tue, 07 Jul 2026 11:30:24 +0000

The community responded with an explosion of tools. Here are all the optimization techniques I've found. Ranked from C-Tier (meme) to S-Tier (serious engineering).

⭐ C-Tier: Use /compact when you're at 60% of the conversation's max context. 60% is the sweet spot. Context tokens aren't all equal, and when you're near the limit, agents start drifting and follow instructions less reliably. Why meme-tier? Because nobody's going to do it manually. (It's done automatically by the S-Tier tool.)

⭐⭐ B-Tier: Compress prompts before they reach the model. In any prompt, roughly half the words carry no real information, and agents are perfectly capable of filling in the blanks. That's why there's a whole category of specialized models for prompt compression with minimal quality loss: LLMLingua or Bear-2, for example. Why B-Tier? It's only really suitable for deterministic workflows (like n8n or similar), not for highly variable agentic environments. But it's excellent in those specific cases.

⭐⭐ B-Tier: Always tell Claude to launch its exploration sub-agents with Haiku instead of Fable, Opus, or Sonnet. This can be up to 92% cheaper on exploratory searches. Haiku is great at digging, not at thinking.

⭐⭐⭐ A-Tier: /effort default to xhigh. All the time. But 80% of what you ask Claude doesn't actually need that level of token waste. Switch to medium or high for most tasks — it cuts the amount of thinking required by 2x or 4x to reach the result.

⭐⭐⭐⭐ S-Tier: Agent harness compaction tool. Why S-Tier? It's plug-and-play and the gains are immediate, no matter what you're doing with your agent. Tokenade, for example, automatically optimizes: the commands the model uses, file re-reads, code/web search, MCPs, the order of tool calls, etc. It currently ranks #1 on THOL (Token-Harness Optimizer Leaderboard), with -27% token cost on 200k+ token conversations and -40% on 400k+ token conversations (Opus & Fable).

Do you use any of these techniques ?

Tokenade : https://tokenade.net/
THOL : https://pi-infected.github.io/token-harness-optimizer-leaderboard/
LLMLingua : https://huggingface.co/spaces/microsoft/llmlingua-2
Bear-2 : https://thetokencompany.com/

Position-1 CTR isn't 30% anymore — what AI Overviews actually do to your clicks (+ a free calculator)

Paul Irolla — Sat, 16 May 2026 08:48:29 +0000

For years, the SEO planning template was the same spreadsheet trick: pull the keyword volume, multiply by an assumed CTR (the famous "31% for position 1"), and call that your traffic projection. In 2026, that math is broken.

What changed:

AI Overviews sit above the organic results on most informational queries. The user often gets their answer in the box and never scrolls.
Featured snippets still steal the click on definitional / how-to queries.
People Also Ask clusters expand inline and burn 6-8 vertical inches of SERP real estate.
Sponsored carousels on commercial intent queries push the first organic result below the fold on mobile.

The result: position 1 organic CTR for an informational keyword in 2026 is closer to 8-15% than to the legacy 30%. For commercial-intent keywords with a sponsored carousel and an AI Overview, position 1 organic CTR can drop to 3-6%.

If you're still planning content with a 30% assumption, your traffic forecasts are off by a factor of 3-10x. Which means the keyword you're killing for "low projected upside" might actually be the one worth shipping, and the keyword you're prioritizing for "30% × 12k searches" is going to disappoint.

What I changed in my own planning

I split CTR assumptions into 4 SERP archetypes:

SERP type	Position 1 CTR (2026)	Position 2-3 CTR
Plain organic (rare)	28-35%	12-18%
Organic + PAA only	18-24%	8-12%
Organic + AI Overview	8-15%	3-7%
Organic + AI Overview + sponsored carousel	3-6%	1-3%

Before committing to a topic, I run the SERP through a quick check: which archetype is it? Then I plug the right CTR into the volume math. That single change cut the gap between my projected and observed traffic by ~70%.

A free thing for the lazy version of you

I built a free in-browser calculator that does this for you — paste the keyword + chosen position + SERP archetype, get a realistic click projection: the-seo-autopilot.com/en/free-tools/serp-ctr-calculator. No signup, all client-side, no email gate. Use it when you're triaging a 200-keyword list and don't want to manually classify every SERP.

There's also a related one I use a lot — a keyword opportunity calculator that combines this CTR adjustment with difficulty / volume / business value to spit out a single ranked score per keyword. Useful when you have a backlog of 50 ideas and need to pick the next 5.

TL;DR

The "30% for position 1" rule of thumb is a 2018 number. Don't plan with it in 2026.
Classify each keyword's SERP into one of 4 archetypes before assigning a CTR.
AI Overviews + sponsored carousels can drop your effective CTR by 5-10x.
Recalibrate. Your "low-volume but high-intent" keywords are probably more valuable than your "high-volume informational" ones now.

Plan your content with the SERP you actually have, not the SERP you wish you had.

What is /llms.txt? — the AI-crawler hint file (+ the free generator I built for it)

Paul Irolla — Fri, 15 May 2026 17:38:46 +0000

Last year a small RFC started making the rounds: /llms.txt. It's a single-file convention that tells AI assistants (ChatGPT, Claude, Perplexity, the Google AI Overview, Copilot…) which content on your site to surface and how to summarize it. Think robots.txt, but for meaning instead of crawl rules.

I've been running an autonomous SEO agent on a SaaS site, and /llms.txt showed up as the cheapest-yield optimization I could ship: a single static file, written once, that materially changes how an LLM frames your brand when a user asks about your space.

This post is what I wish I'd read before writing my first one.

What `/llms.txt` actually contains

The format is intentionally minimal — a markdown file at your domain root:

# Acme — autonomous test runners for SaaS

> One-line description of the project, exactly the way you'd want an
> LLM to re-quote it.

## Docs
- [Getting started](https://acme.dev/docs/start.md)
- [API reference](https://acme.dev/docs/api.md)

## Examples
- [End-to-end test for a Stripe checkout](https://acme.dev/examples/stripe.md)

## Optional
- [Pricing](https://acme.dev/pricing.md)

Three things matter:

The summary line is the brand-positioning weapon. If a user asks "what is Acme?", the LLM is statistically going to lift this line. Write it like the headline you'd put on a billboard, not like a feature list.
Sections are signals. "Docs" / "Examples" / "API" tell the LLM what surfaces are worth pulling into a citation. The order matters — what you list first gets weighted higher.
Optional vs required. The ## Optional section is content you'd be happy to see referenced, but don't need surfaced. Pricing, blog posts, careers — that kind of thing.

What it's NOT

It's NOT a robots.txt. AI crawlers will still hit your site without one.
It's NOT a sitemap. It doesn't enumerate every URL — it picks the important ones and tells the LLM how to frame them.
It's NOT machine-validated. There's no "llms.txt parser" that errors out on bad syntax. The LLM does its best with whatever you write. So write it well.

How to validate yours

I built a free in-browser generator that does the formatting + a sanity check on the structure: the-seo-autopilot.com/en/free-tools/llms-txt-generator. No signup — it's all client-side. Paste your site description, your section URLs, hit generate, copy the markdown into your site root.

If you want to see one in production, mine is at the-seo-autopilot.com/llms.txt. It's also indexed in SecretiveShell/Awesome-llms-txt — a curated list of all the public /llms.txt files in the wild, which is where I'd recommend looking before writing your own.

Does it actually move the needle?

Honest answer: too early to say with high confidence in 2026, but the signal is positive. Sites with a well-written /llms.txt get cited more often in ChatGPT and Perplexity answers in the niche I track (programmatic SEO + indie SaaS). The cost is roughly an hour, the upside is "free distribution surface that didn't exist 18 months ago."

Worth shipping.

I'm running an autonomous AI agent that publishes a fact-checked SEO article every day — here's the stack

Paul Irolla — Fri, 15 May 2026 16:18:46 +0000

For the past 60 days I've been running an experiment: an AI agent owns the entire SEO pipeline of one of my SaaS sites. Keyword research, drafting, fact-checking, internal linking, schema markup, scheduling — the agent does it all. Zero human touch on the content side.

Results so far: 0 → 400K+ Google impressions in 60 days. 46 articles live, 330+ scheduled. No backlinks bought, no paid promotion.

I'm sharing the stack because every "AI SEO" tool on the market today is either a glorified ChatGPT wrapper or charges $1k+/mo for marginal automation. The agent below runs on a small VPS in a Python loop and costs me less than $100/month in OpenRouter API credits.

The pipeline

Keyword pipeline — a daily cron pulls the SERPs of ~300 seed queries via DataForSEO, scores by intent × difficulty, picks the next batch.
Drafting — a frontier model writes a first draft against a structured outline. Cost: ~$0.10 per article.
Fact-check pass — a smaller, cheaper model re-reads the draft with a "find every factual claim and verify it has a credible source" prompt. Anything dubious gets flagged.
On-page — JSON-LD schema, internal links to existing articles via cosine similarity on embeddings, title/meta optimization.
Scheduling — one article goes live per day at a fixed time. The cadence matters more than the volume of any single drop.
Monitoring — a tiny script pings Google Search Console weekly and surfaces underperformers for the agent to refresh.

What I've learned

Quality from AI agents is fundamentally a context problem. The agent gets the keyword + the SERP context + the existing internal-link graph + a brand voice guide. With those inputs, modern LLMs write better than most freelancers I've hired for the same money.
The fact-check pass is the unlock. Without it, AI articles confidently hallucinate stats. With it, they're often more reliable than the median human content for the same niche.
Publishing daily compounds. Google indexes a healthy domain quickly when the cadence is regular. The 60-day curve looked basically flat for the first three weeks, then bent up.
Most "AI tool" directories will reject you if you aren't actually a tool. A playbook is not a tool. A free in-browser /llms.txt generator IS a tool. Frame accordingly when you submit.

Tooling

The site ships a free /llms.txt generator plus 12 other one-shot SEO tools (JSON-LD schema generator, SERP CTR calculator, hreflang tag generator, etc.) at the-seo-autopilot.com/en/free-tools — no signup, all client-side.

The full architecture writeup, prompts, and scheduler code are documented at the-seo-autopilot.com for indie SaaS founders who want to copy the setup. Happy to dig into specific bits in the comments — particularly the fact-check prompt, which is the part I had to iterate on the most.

Dominate LinkedIn in just 5 minutes a day

Paul Irolla — Sun, 10 Aug 2025 13:10:19 +0000

That’s not clickbait.
That’s exactly what Meet Lea was built for.

Here’s the problem:

You know you should post regularly… but blank page syndrome is real.

You want to engage with your audience… but comment replies eat hours.

You’d love to track what works… but analytics feel like a chore.

Lea solves all of it.

✅ Create posts that actually perform — Turn any idea, article, or file into a ready-to-publish LinkedIn post in seconds.
✅ Engage without the burnout — Lea suggests smart, human-like replies to every comment.
✅ Know exactly what to post next — Intelligent content analysis tells you what your audience truly cares about.
✅ Grow with clarity — Engagement tracking, growth insights, and post ideas… all in one dashboard.

Who’s already using it?
Freelancers. Agencies. Marketing managers. Community builders.
Over 500 people are on board — and in beta, Lea has already generated:

107K sources of content
17K post ideas
3K full posts
19K comments

This is your unfair LinkedIn advantage.
Access is limited. The waitlist is filling fast.

🎁 Join now and get:

Priority access

7 days free

Early adopter perks

🚀 Stop overthinking. Start dominating.
👉 Join the waitlist today.

https://meet-lea.com

DEV Community: Paul Irolla

Claude Code /compact: What It Costs and What Survives

TL;DR

What /compact actually does

What compaction costs: warm cache vs cold cache

What survives compaction, and what quietly disappears

When auto-compact fires

/compact, /clear, /rewind, /recap: which one, when

Steering what the summary keeps

Measuring what compaction did to your session

Common mistakes

What to do this week

FAQ

Related reads

Claude Code Hooks: Which Ones Add Tokens, Which Cut Them

TL;DR

What a hook is, in cost terms

The hooks that add tokens

The hooks that cut tokens

The 10,000-character ceiling

Hooks that call a model

PreModelSwitch: the first native cost signal in a hook

Common mistakes

What to do this week

FAQ

Related reads

Claude Code Subagents Token Usage: What They Really Cost

TL;DR

What a subagent is, in token terms

The startup bill: what loads before the first tool call

What I measured on my own sessions

How to measure the token cost of each subagent

When a subagent saves tokens, and when it burns them

Settings that shrink the bill

Common mistakes

What to do this week

FAQ

Related reads

I open-sourced Tokenade, my token optimizer for coding agents. Here is why the paid model did not hold

Why the paid model did not hold

What it does

The number

Try it

Anthropic admitted that Fable burned through their €200/month Claude Code plan in 1 hour instead of 5.

Position-1 CTR isn't 30% anymore — what AI Overviews actually do to your clicks (+ a free calculator)

What I changed in my own planning

A free thing for the lazy version of you

TL;DR

What is /llms.txt? — the AI-crawler hint file (+ the free generator I built for it)

What /llms.txt actually contains

What it's NOT

How to validate yours

Does it actually move the needle?

I'm running an autonomous AI agent that publishes a fact-checked SEO article every day — here's the stack

The pipeline

What I've learned

Tooling

Dominate LinkedIn in just 5 minutes a day

What `/llms.txt` actually contains