Three hooks and a ratchet: Session Optimizer, traced through its source
Three plugins sit on three points of a Claude Code session. One reads your prompt before the work starts and asks for the vague words to be bound to real artefacts. One watches the size of the conversation and stops it twice, once to reflect and once to hand over. One puts the numbers you would otherwise have to guess at on a single line of your terminal. They share no process and no database, only a few files under your home directory, and nothing they compute leaves the machine.6
Three plugins, three moments in a session
None of these plugins is a program you run. Each one registers on a point the host already emits, does a bounded amount of work, and gets out of the way. The refine gate reads a prompt before it reaches the model.1 The statusline re-installs itself at session start and is re-rendered by the host on a short interval.2 The context guard runs at the end of each turn, and once more when a subagent finishes.3
The design rule shared by all three is that failing quietly beats interfering. The gate is explicit about it: a gate that can block your prompt is worse than no gate at all.4 The guard exits zero on any parse or IO error, because a Stop hook that wedges a session is worse than a missed checkpoint.5 Neither behaviour is a promise in a README; both are the first thing their files say.
What the refine gate hears, and what it says back
“The previous fix is still broken, make it work like before.” Every noun in that sentence points at something the model cannot see. The gate recognises the shape of that problem rather than its subject matter: seven regular expressions over five classes of unbound reference, drawn from mis-bindings that actually happened rather than from imagination.8
Its second tier is the more interesting one, because it is structural. A prompt that reads as a request for work but contains no path, no filename, no commit hash and no line reference is a prompt nobody can check the result of.9 The reasoning is written into the file: no gate can enumerate every domain vocabulary, so it tests for grounding instead, and a prompt you grounded yourself is left alone.10 On a match it injects instructions; on no match it prints nothing, so the common case costs no context at all.11
Two thresholds, and a ratchet that only turns one way
At the end of every turn the guard reads the tail of your transcript rather than the whole file, stepping backwards in 64 KiB blocks under a hard 4 MiB cap. That size is not a guess: the file records the measurement it came from, a 24.5 MB transcript whose last usage record sat 7 591 bytes from the end.15 From that record it sums three fields into one figure, the input tokens plus both cache fields, and compares it to the thresholds for the model you are on.1416
What happens next is the part worth understanding before you install it. Both thresholds return the same verdict to the host: block.17 The warning is not advice you can ignore; it is a single interruption that writes a checkpoint and asks for a reflection pause, after which the session continues.20 The hard threshold interrupts once more and asks you to clear and resume.21 Neither can fire twice, because the highest level reached is remembered per session.18
Three measurements that must not be added together
A large current context and a large cumulative spend are different facts. The context figure is main-thread only and deliberately excludes the children, because mixing subagent tokens into it would trigger checkpoints at the wrong moment; the children's spend is reported beside it instead.1425 The aggregate that holds it is keyed by agent id, so a repeated event updates an entry rather than doubling it, and sibling transcripts are swept in case an earlier event was missed.26 One layer down, assistant turns are deduplicated by message id with the largest usage winning, because the host re-logs the same turn across forks and resumes.27
The statusline then applies a rule that is easy to state and easy to get wrong: counts and token volumes come from the aggregate, and every dollar figure comes from the ledger alone, so the same spend is never priced twice on one screen.313235 When the terminal is narrow it drops from the tail, keeping the leading segments, because the host payload carries no width field and the layout has to probe for one.2930
What these three plugins do not prove
The end-to-end result is a better-grounded request, visible session signals and a written restart point. The code supports that workflow; it does not establish that the instructions were obeyed, that the implementation that followed was correct, or that a summary kept every fact that mattered. Those need review. Three further limits are worth knowing: the pattern matching is English and syntactic, not an understanding of your sentence8; the temporary files are under /tmp and do not survive a reboot25; and the cost of a full statusline refresh, in milliseconds, is measured nowhere in the sources, which document only the paths that avoid work.33 One detail is a deliberate choice rather than an omission: there are no emoji anywhere, because a glyph has to be learned and several break the column budget.34 The lines are rendered identity first.28