Overkill

Overkill

ccusage and its siblings will tell you exactly what you spent. They will not tell you whether you needed to. That second question — was this task worth the model and effort level actually used on it — requires reading what the task was, and that's the layer a stats tool structurally can't provide. Overkill is that layer.

What it does, in order

0. On every invocation: check whether recurring mode is already set up

A skill file cannot run itself — it only executes when something triggers it. So the closest honest path to "install once, don't think about it again" is: the first time this skill runs for a given user, for any reason, it also sets up its own recurring check — turning "remember to run this" into "you only ever had to trigger it manually once."

Before producing a report, check for a marker at ~/.overkill/autonomous.json. If it exists, skip straight to Step 1 — recurring mode is already active, don't ask again.

If it does not exist, this is the first run. After producing the report the user actually asked for, ask once — plainly, not buried — using this shape:

"Want me to set this up to check automatically from now on, so you don't have to remember to ask? I'll use [/schedule / your harness's cron tool — name whichever is actually available] to run a cheap daily check, and only bother you if it finds real waste (over $5 or 20% of spend). [Persistent across restarts / only for this session — state which, honestly, based on what the harness actually offers] Set it up?"

On yes: create the recurring job per the harness's actual primitive (see "Autonomous mode" below), write the marker file recording what was set up and its real scope (persistent vs session-bound), and confirm plainly what was actually created. On no or no response: proceed without it, and do not ask again this session — repeated nagging after a clear no is worse than the manual-trigger problem this exists to solve. Never create the recurring job silently without this ask, even on a first run — standing infrastructure gets explicit consent, always.

1. Pull real usage data

Reuse ccusage (or the equivalent for whatever agent CLI is in use — it supports Claude Code, Codex, Amp, Droid, Gemini CLI, and a dozen others) for the requested window. Default to the active block / last 7 days if the user didn't specify. Do not re-derive token/cost accounting by hand — that's a solved problem, solved well, reuse it:

npx -y ccusage@latest blocks --active --json
npx -y ccusage@latest daily --json

2. Recover what the work actually was — delegate the reading, don't do it inline

Cost data alone is silent on task content. Cross-reference the usage window against what's actually available: recent session transcripts if the harness exposes them on disk, the current conversation's own history if this is a live self-check, or ask the user directly to point at what they worked on if neither is accessible. Do not skip this step and fall back to guessing from token counts alone — a big token count means nothing about whether the effort was justified without knowing what happened.

If a transcript needs reading and a subagent dispatch primitive is available, delegate the raw read to a cheap, read-only agent rather than reading it inline in whatever model tier is currently running Overkill. Extraction — skill invocations, tool-call patterns, retry/failure language, rough shape of what was worked on — doesn't need flagship judgment; only the classification in Step 3 does. If a scout-type persona is configured (read-only, cheap tier — see the scout/implementer/reviewer agent stack if installed), dispatch to it and have it return a condensed structural summary, not the raw transcript. Running this step at the orchestrator's own tier when that tier is expensive is precisely the kind of overkill this tool exists to catch — it should not commit that mistake against itself.

3. Classify each meaningful unit of work

For each distinct task/session in the window, judge its actual complexity from its content, not its cost:

• Trivial — renames, formatting, single-line fixes, simple lookups, boilerplate. Should run at low effort, cheapest capable model.
• Standard — typical feature work, debugging with a clear repro, well-scoped changes. Medium effort is usually enough.
• Complex — architecture decisions, ambiguous multi-file debugging, correctness-critical logic. High/max effort and the top-tier model are earned here.

This is judgment, not a formula — state the reasoning for each classification, not just the label, so the user can disagree with a specific call rather than trust a black box.

4. Flag two distinct failure modes

Overkill — effort/model actually used was higher than the task's classified complexity justified. This is the namesake failure: paying premium rate for standard or trivial work.

Slow failure — the inverse and easy to miss: a task retried the same approach repeatedly at a low tier before finally escalating, paying for N failed cheap attempts instead of escalating sooner. Cheap-but-wrong repeated four times can cost more than expensive-but-right the first time. Flag this as distinctly as overkill — it's the same underlying mistake (wrong tier for the task) in the other direction.

5. Price each flag — and label the precision honestly

Usage tools typically report cost at the block or session level, not per tool-call or per-invocation. This means a specific flagged item (one skill invocation, one task) usually cannot be priced exactly — only estimated proportionally against the block's real totals. Every dollar figure in the output must be explicitly labeled:

• measured — only when the harness/usage tool actually exposes cost at this granularity. Rare; check before claiming it.
• estimated — a proportional estimate against real totals, clearly marked as such. This is the common case. Say so plainly instead of presenting a specific-looking number as if it were measured fact.

A specific dollar amount with no precision label is a claim this skill exists to prevent elsewhere — do not make it here. If a flagged item can only be described qualitatively (real, identifiable in content, but not priceable at all with available data), say exactly that rather than forcing a number.

6. Produce the report

OVERKILL — [window]
Total spend: $[X] across [N] tokens, [M] sessions   (measured)

flagged — overkill: [dollar figure + "(estimated)" or "(measured)", or
  "(not priceable with available data)" if genuinely neither]
  [task] — classified [tier] because [reason, from actual content].
  [repeat per flagged item, most confident/highest-impact first]

flagged — slow failure: [same precision-labeling rule applies]
  [task] retried [N] times at [tier] before escalating to [tier].
  [reason it should have escalated sooner, or been scoped as a /goal
  with an explicit escalation condition]

not flagged: [dollar figure + precision label] — tier matched complexity.

fix — drop this in CLAUDE.md:
  [a specific, personalized effort/routing policy derived from what this
  window's data actually showed, not a generic template]

Never emit a bare dollar figure without one of the three precision markers next to it. If most or all of the flagged items land in "not priceable," the report is still valuable — it named real issues — but say plainly that the dollar total under-represents them rather than let a partial number imply completeness.

Lead with the flagged total and percentage — that's the number that matters. Show the full breakdown below it for anyone who wants to verify the reasoning rather than trust the summary.

Autonomous mode (optional — off by default)

Overkill does not run on its own after install. Left as a manually triggered skill, it only catches waste when someone remembers to ask — which defeats a real part of its purpose. Autonomous mode closes that gap, but it is standing infrastructure (a recurring scheduled job), not a default — set it up explicitly, once.

Use whichever recurring-task primitive your actual harness provides — do not assume one specific command. These are genuinely different in an important way, and claiming otherwise would be exactly the kind of overclaim this tool exists to catch elsewhere:

• Claude Code CLI: /schedule — moves a routine to the cloud, persists independent of any open session.
• Cowork / other harnesses with a cron-style tool: typically session-scoped — the job lives only as long as the current session, and even recurring jobs commonly auto-expire after a bounded window (e.g. 7 days) regardless of activity. Check this before telling the user it's "on" indefinitely — say plainly if what's being set up is bounded to the current session, not persistent.
• No recurring-task primitive available: say so, and offer the manual trigger as the fallback rather than silently doing nothing.

Setup prompt, adapt to the primitive actually available:

[schedule/cron primitive] daily: run overkill in usage-only mode (cheap —
no full content analysis). Only if flagged waste exceeds $5 or 20% of
spend for the day, escalate to the full report and notify me. Otherwise
log silently and stay quiet.

Two design rules this depends on, and both exist to prevent the tool from becoming its own first flagged item:

1. The recurring check must be cheap. Usage-only mode (ccusage data alone) daily, not the full content-correlated pass — that's expensive and only worth running when the cheap check already suggests something is off.
2. Notify on threshold, not on every run. A daily message with nothing to say trains the user to ignore it within a week. Silence is the correct output on a clean day — say so in Section 6's report logic.

Learning from corrections (self-improvement — what this honestly means)

This is not the underlying model getting smarter, retrained, or fine-tuned — that claim would be false, and this tool exists specifically to catch claims like that elsewhere. What it actually is: a small local file the skill reads before classifying and writes to after a run, building an accumulated, user-specific record over time.

File: ~/.overkill/history.md (create if absent).

On disagreement: if the user corrects a classification ("that wasn't trivial, it touched auth logic"), append it: the task description, the classification given, the correction, and why. Before classifying anything in a future run, read this file and treat prior corrections as precedent for similar patterns — the goal is that the same mistake doesn't get made against the same user twice.

On adopted fixes: when the user pastes a recommended routing policy into their CLAUDE.md, log it with a timestamp and the category it targeted. On a future run covering the period after that date, check whether spend in that specific category actually dropped — and report that plainly, including if it didn't. This is the only honest way to claim the tool's own recommendations work: show the before/after, don't assert it.

What this buys, honestly: classification calls that converge toward what this specific user actually considers correct, and recommendations that get checked against reality instead of trusted on faith. What it does not buy: a smarter model, generalization to other users' preferences, or improvement without the user ever having corrected or adopted something. If the history file is empty, say so and classify from the base rules in Section 3 — do not imply learning that hasn't happened yet.

What this is not

Not a replacement for ccusage — it's a required dependency, not a competitor. Not a guess from token counts alone — if session content isn't recoverable, say so plainly and scope the report to what can actually be judged, rather than producing confident-sounding waste estimates from cost numbers alone. Not a one-time report — the real value is running it regularly enough to catch a routing habit before it compounds over weeks. Not self-improving in the sense of a smarter model — a local, honest correction history, nothing more, nothing hidden.