cctop / Panel guide / Advisor
cctop-insights skill answers from the same numbers — or run cctop advise. cctop coach-stats shows how often each rule fired, was acted on or snoozed.36 deterministic rules over the same data the other panels show — no model call, no network, never a keyword in your prompt. Each rule fires on a concrete threshold from this session's own evidence (a tool result, a denial kind, an interrupt marker, an API-error line, a git operation) and says what it found and the change to make. The coach keeps one nudge in a slot by class — NOW interrupts, NEXT waits for the turn's end, LATER waits for a free slot — with a fixed lifetime per class, a cooldown per rule, and an acted test that retires the nudge the moment you did the thing. x snoozes it for five turns, X for the session; three snoozes in a row and the rule stays quiet on its own. The Advisor panel lists the slot's occupant first, then what is queued behind it.
~4k/turn
Grouped by the class the rule fires in. The token-axis rules (A01–A30) watch what the session costs; the outcome rules (A32–A47) watch whether the work is converging.
Fires whenthe cache entry expires within the countdown band while the person is asked (or idle) and a reply now would keep ≥ 50 k warm.
The cache entry that holds your context expires on a fixed clock (5 minutes, or 1 hour when the session runs on the longer TTL). While it is warm, a reply costs a cache read of the whole context; once it expires, the next request re-writes it at the cache-write price. Answering a pending question before the countdown ends keeps the entry alive; if the task is done, a hand-off note and /clear is cheaper than a warm keep-alive.
Fires whena model switch while the cache is warm and the context large (from `PreModelSwitch` when hooks run, else a `/model` or `/fast` row of history.jsonl); when the cache is cold and this project switches a lot, the cheap moment is named instead.
Switching the model (or /fast) while the cache is warm throws the entry away: the new model cannot read the old one's cache, so the next request re-writes the entire context at the cache-write price. Claude Code confirms a warm switch; the priced figure and the undo are what cctop adds — switch back before the entry dies, or switch right after a /clear when the context is small.
Fires whena commit landed with unchecked source edits since the last commit; escalated when the latest test in that window failed.
A commit that lands with unchecked source edits, or right after a failing test, is a rework trap: the next push runs CI on it and the fix arrives as a second commit or a force-push. Run the session's own test command before the push and amend. Commits of documentation only are exempt.
Fires whentwo corrections within four human turns: interrupts, refused calls, feedback on a call.
Two corrections close together — an Esc and a short steer, a refused call, feedback on a call — on the same work mean the model's understanding drifted and the steers are patching it. Esc Esc (or /rewind) restores the conversation and the files to the checkpoint before the drift, so the restated prompt starts clean; bash-written files are not covered by the checkpoint. cctop counts only structural markers, never keywords in the prompt.
Fires whenthree consecutive failed calls (denials excluded) in the last ten of the turn, two sharing a command prefix, no edit between.
Three failed calls in a row with two of them the same command shape is a blind retry: the model repeats the same guess with small variations and each failure adds its error text to the context. Interrupt and supply the missing fact (a path, a flag, an environment detail), or run the command yourself and paste the first twenty lines. Denials are not counted here.
Fires whenClaude waits on you: a question, a permission dialog, a notification, or a `?`-ended turn with nothing back for 30 s.
When Claude asks a question, waits on a permission dialog, or ends the turn with a question, nothing happens until you answer — and the cache entry holding the context keeps expiring on its clock. A one-word reply within the warm window keeps the whole context at the cache-read price; a reply after the entry died re-writes it all.
Fires whena destructive git command ran on a dirty tree this turn.
Rewind restores files that Claude edited with Edit and Write, not files that a shell command changed. A git command that rewrites the tree (reset --hard, checkout -- ., clean -f, stash drop, push --force) on a dirty tree can lose work no checkpoint holds; git reflog and git stash list are where it may still be.
Fires whenthe IDE and Claude edited the same file this turn.
When your editor and Claude write the same file in one turn, one of them is working from a stale copy; the next Edit fails on old_string or silently drops your change. Say which version wins before the next edit, and let Claude re-read the file.
Fires whenauto mode blocked the same command shape twice (or a settings rule denied it once): the allow rule, or the alternative.
Auto mode blocks a command shape by a classifier; a second block of the same shape within a turn (or three turns) means the model will keep trying variants, and three blocks in a row pause auto mode. An allow rule — Claude Code's own suggestion when it made one, else Tool(argv0 subcommand:*) — lets the shape through; a bare Bash rule allows everything and is never suggested. A settings deny rule is different: the model cannot run it, tell it the alternative.
Fires whenthe turn died on an API error line.
The turn ended on an API error, not on a reply. A rate limit (429) resets on the account's clock — another model family has its own limit; a spend limit or an authentication failure stops everything until it is fixed; 'prompt too long' means the context exceeds the window and only /compact or /clear helps; a server error is retried by Claude Code itself. Re-sending into the same error costs the wait again.
Fires whena compaction happened (exact `compact_boundary`; inferred from the drops between API calls before 2.1.263) and either the compacted context is still within 20 k of the threshold, or it was the second one.
Each compaction spends output tokens on a summary and loses detail the model then re-reads. When the compacted context is still near the threshold it re-triggers within a few turns. /compact <focus> at a clean stop, while the cache is warm, keeps what matters; two compactions in one session usually cost more than a hand-off note and a fresh session.
Fires whenone command shape approved ≥ 3 times, or > 2 min spent on permission prompts; the rule text is Claude Code's own suggestion.
While a permission prompt is open the model does nothing and the wall clock runs. A command shape approved again and again is a candidate for the allow-list (permissions.allow in settings); Claude Code's own suggestion (permission_suggestions[].ruleContent) is the safest rule, and a bare Bash rule is never it.
Fires whenthe 5 h limit is projected to run out before it resets. A limit already hit is A47's (turn died), not a pacing matter.
Rate limits are account-wide and reset on a fixed schedule. If the current burn reaches 100 % before the reset, the session stops mid-task. Claude Code's own levers: /model sonnet roughly doubles the runway, /effort medium trims output; moving exploration to cheaper subagents or pausing heavy work until the reset avoids the cut-off.
Fires whenthe cache is cold and this project switches models often: now is the free moment.
When the cache is cold anyway, the next request re-writes the context whatever you do: a model or effort switch costs nothing extra at that moment. Pick the model for the next stretch and hold it until the next /clear.
Fires whenthe cost of continuing: what every call re-reads at this context. In the `next` row from 200 k; the slot only at a clean turn end above 300 k on a 1M window (or the warn band elsewhere).
Every API call re-reads the whole context at the cache-read price, and a turn is many calls. Past 300 k on a 1M window each call costs several times what it did at 100 k, so a clean stop (end_turn, nothing in the background) is the moment to /compact with a focus or to write a hand-off note and /clear. The projection uses this session's own calls per turn, never a constant.
Fires whenthe current read-only run (Read / Grep / Glob / WebFetch and the Bash allowlist) grew past 8 calls and 20 k tokens (or 6 and 25 k); retires when the run ends or an Agent spawns.
A run of read-only calls (Read, Grep, Glob, cat, rg, git log…) in the main thread fills the main context with raw files that persist until compaction. An Explore subagent does the same search in its own context and hands back a paragraph. The counter resets on any write or an Agent spawn.
Fires whena `/loop` or `/goal` is armed on a large context: every wake-up re-reads it.
A /loop or /goal wakes the session on a timer, and each wake-up sends the whole context again as a cache read even when nothing happened. On a large context that is millions of tokens an hour of idle time: /clear before arming the loop, widen the interval, or narrow it to the check it needs.
Fires whena cold resume: the session idled past the cache TTL on a large context, or Claude Code's own resume said the cache likely expired.
The session sat idle longer than the cache TTL with a large context: the entry is gone and the next message re-writes it all. If the task is done, a hand-off note and /clear start the next one at a fraction of the size; if not, /compact halves what comes back.
Fires whensource edits without a test run: nudged at the turn's end once ten minutes or fourteen calls passed since the first unverified edit.
Source edits with no test, build or type-check between them accumulate unverified assumptions; the later a failure surfaces, the more of the turn has to be redone. A test run right after the edit is cheap (its output is short) and lets the model fix the failure while the file is still in context. Reads of an edited file count as a check too — only when Claude re-reads the whole result. Documentation edits and sessions that have never run a test are exempt.
Fires whena PR is open (created, pushed) with a substantial diff and no review pass; once per PR.
A pull request with a substantial diff and no review pass carries whatever the writing session assumed. /code-review runs in a fresh context that has not seen the reasoning behind the diff and checks the change on its own terms; a review agent or review skill this session counts as done. Once per pull request.
Fires whena natural boundary (a task completed, a done/next prompt, a question-ended turn) on a large context: the moment to hand off.
A completed task, a 'done' or 'next' from you, or a turn that ended with a question is a natural boundary. On a large context every later call re-reads everything before the boundary; a hand-off note, /rename and /clear start the next task at the size of the prefix. Never on a commit alone, never while background tasks or a loop are still running.
Fires whena named cache miss (`diagnostics.cache_miss_reason`, or the status line's `prompt_cache.last_miss_cause`) that re-wrote ≥ 20 k tokens within the last three human turns.
A named cache miss means the API could not reuse the cached prefix: a model switch (model_changed) re-writes the entire context at the cache-write price, a changed tool list (tools_changed: an MCP server connecting, ToolSearch loading a deferred tool, a CLI older than 2.1.267 rebuilding the list) re-writes everything after the tools, and a rewritten earlier message (messages_changed: a rewind or an edited turn) re-writes from that point. Each is a one-off cost the size of the context; the fix is timing — switch models and load tools early, or right after /clear.
Fires whena prompt gap longer than the cache TTL followed by a full-context re-write, within the last three human turns (post-mortem; the preventive countdown is A19).
A cache entry lives 5 minutes (or 1 hour, as the API reports for this session). After that, the next request re-writes the entire context. Batching questions or answering within the TTL avoids the cold write; a cold turn on a 400k context costs as much as ~20 warm ones.
Fires whenone tool type's kept results since the last boundary pass `/context`'s own thresholds (≥ 15 % of the window and ≥ 10 k; Read ≥ 5 %), or a single kept result ≥ 10 k tokens.
Every byte of a tool result stays in context for the rest of the session and is re-read (and billed) on every later request; /context flags a tool once its results pass 15 % of the window. Narrow the command (head, grep, Glob) or delegate the exploration to a subagent that returns a summary. A result Claude Code spilled to disk (<persisted-output>) kept only its head; the rest cost the run, not the context.
Fires whenedit → re-read → edit churn on one file, or a file read ≥ 3× whole with no edit in between (Bash `cat`/`sed -n`/`head`/`tail` count; ranged and unchanged reads do not).
Reading a file again re-injects it whole. After an Edit the new content is already in the tool result, so an edit → re-read → edit sequence pays for the file twice. A Read with offset/limit on the relevant range costs a fraction; better, ask Claude to keep the lines it needs in its own summary.
Fires whenprefix weight nobody uses: an MCP server idle > 20 min whose schemas cost > 2 k tokens (plus its ToolSearch rebuilds), or an enabled plugin with > 2 k always-on tokens unused for ≥ 10 startups.
Every MCP server's tool schemas and every enabled plugin's always-on text are part of the prefix sent on each request, whether or not they are used, and each ToolSearch load of a deferred tool rewrites the cached prefix. A server or plugin with no calls for a long stretch is pure overhead: disable it for this project (.mcp.json, /plugin) or rely on deferred loading.
Fires whenthinking > 40 % of output over five edit-heavy turns at an effort above medium.
Thinking tokens are billed as output. On routine edits the model rarely needs deep reasoning; a lower effort level cuts thinking without changing the edit. Reserve high effort for design and debugging. On models other than Fable the effort level is part of the system prompt, so change it at a boundary (after /clear) to avoid a cache re-write.
Fires whena foreground Bash call longer than 60 s in the last five turns (calls Claude Code backgrounded itself do not count).
A foreground Bash call blocks the turn until it exits. For builds and test suites that take more than a minute, run them in the background (run_in_background): Claude keeps working and is notified when the command finishes. Calls Claude Code backgrounded itself do not count.
Fires whena paste of ≥ 20 k characters or ≥ 200 lines in history.jsonl matched to one of the last three human turns (a queued steer's paste lands inside the turn that absorbed it), or a turn whose first API call carried > 5 k uncached `input_tokens` (sessions without a prompt cache). The paste's size comes from history.jsonl — inline characters, or the composer's `+N lines` placeholder for a hashed paste — never its text. On a cached session the paste is not `input_tokens` at all: Claude Code writes the new prompt into the cache, so it lands in the first call's `cache_creation_input_tokens` with the previous turn's tail, which is why the size is read from the history and not from the usage.
A large paste is new context: on a cached session Claude Code writes it into the cache on that turn's first call (cache_creation_input_tokens, at the cache-write price) and every later call re-reads it; without a cache it is billed as plain input. cctop sizes the paste from history.jsonl — the inline characters, or the composer's +N lines placeholder when the text is only a hash — never from its text, and matches it to the turn by time, so a paste queued mid-turn counts too. Point Claude at the file (it reads only what it needs) or paste the relevant slice.
Fires whenmedian prompt < 32 chars and > 20 human turns in the last hour.
Every turn re-sends the whole context, cache reads included. Many tiny prompts multiply that cost; one prompt with several instructions costs a single context read and usually gets a more coherent answer.
Fires whenan Opus subagent that only searched: ≥ 5 search-shaped calls and no edit.
Search, listing and summarising subagents do not need the most capable model. A subagent that made many searches and no edits runs equally well on Sonnet or Haiku at a fraction of the cost, and leaves Opus for the reasoning-heavy main thread. Explore agents already default to a cheaper model on recent versions; other agent types inherit the session's model unless told otherwise.
Fires whenhook time > 10 % of turn time over the last five finished turns, naming the slowest hook (`cctop hook` itself excluded).
Hooks run synchronously inside the turn. A slow PostToolUse or Stop hook adds its full duration to every tool call or turn. Make expensive hooks asynchronous ("async": true), or narrow their matcher to the tools and paths they care about.
Fires whenthe fixed prefix costs ≥ $0.25 per turn at the cache-read price, or, once a `/context` has measured it, is ≥ 50 k tokens. The prefix is paid on every request, so its cost is absolute, not a share of the window (context-residency PRD, decision 9: a share-of-window rule is inert on a 1 m window, a share-of-size rule fires on half of all sessions). The figure is the residency model's — the `/context` table's when one ran, lowered at a boundary that landed below the first call's. The token arm waits for that calibration (PRD §10.6): the raw first call overstates the prefix by a third and runs 47–62 k on a plugin-heavy setup, so an `Estimated` figure over 50 k gets the sources inspector's own invitation to run `/context`, not a nudge. The price arm reads either figure. Acted on when the person opens either inspector (`i`, `m`).
The fixed prefix (system prompt, CLAUDE.md, tool schemas, skills, plugins) is sent on every request. Even as a cache read it is billed on every call, so its cost per turn is prefix × cache-read price × calls per turn; it fires from 50 k tokens whatever the window, because the cost is absolute — once a /context you ran has measured the prefix, since the first call's own figure overstates it by about a third. Trim CLAUDE.md, move rarely used rules into skills, and disable MCP servers and plugins you do not use in this project. On the Context panel, i breaks the prefix down and m shows what else fills the window.
Fires whenmoney that went to agents whose work did not come back: the agents ledger's waste is ≥ $1 and ≥ 25 % of the agents' spend, over at least two classified agents (agent PRD US-006). Structural evidence only: the task notifications' statuses and result lengths, the workflow journal, the agents' states and the hook spool.
An agent's calls are billed whether or not its result comes back. A failed or killed agent, one that completed with nothing in its result, and one that has gone quiet mid-run are money the session spent for no answer; the agents view (6, Enter) lists each with its cost and the reason, and the task notification's own status is what it goes by. Before launching another of the same kind, look at why the last ones did not return — a prompt that asks for a result, a narrower task, or the parent doing the work itself.
Fires whena feature-sized prompt with plan mode off and no plan yet: the `next` row only.
A feature-sized prompt (long, or naming several files with an implementation verb) sent with plan mode off makes the model act on its first interpretation. Plan mode (Shift+Tab) or a 'plan first' line costs one short turn and produces a checklist you can correct before any file changes; the edits then follow the corrected plan. This is the next row only: it never takes the slot.
Fires whenthe context crossed 150 k / 300 k / 450 k with the last long prompt far behind and no instructions re-injected since: the `next` row only.
On a 1M window the model's attention to instructions given hundreds of thousands of tokens ago fades, and Claude Code re-injects CLAUDE.md only at boundaries. When the context crossed 150 k, 300 k or 450 k with your last long prompt far behind and nothing re-injected since, restating the three constraints that matter (or moving them to CLAUDE.md) is cheaper than the drift. The next row only: it never takes the slot.