zzg
8a775b71fb
A finding you have to remember to go and look at is a finding you do not see. This closes the loop: `fathom insights` reports findings for other programs, a Claude Code Stop hook runs it when a turn ends, and /insights shows the detail on request. The CLI reports as text, --json, or --jsonl, and --new returns only what has not been reported before. The server owns the reported-findings state, because two sessions can end at the same moment and a read-then-write would have both report the same thing. Two rules follow from running on every turn: - It must be fast. --hook asks a running server for an analysis already computed rather than doing one, and never falls back to analysing directly, which could take seconds. Measured at ~20ms whether or not a server is up. - It must never disrupt the session it observes. Every path exits 0 and prints at most one line. A Stop hook exiting 2 tells Claude Code to keep going rather than stop, so a crash here would hijack the session it was supposed to quietly watch. Surfacing is a higher bar than appearing in the tab, and biased towards silence. A tab is consulted; a notification arrives whether or not you wanted it, and the costs are asymmetric -- a missed finding waits patiently, a wrong nudge trains you to ignore all of them. Medium severity and $0.50 minimum, not already reported unless it has recurred since, and at most one nudge every two hours. A local model, if one is running, can veto a finding as not worth interrupting for. It can never promote one that did not clear the bar, is never consulted about findings below it, and a model failure keeps the finding rather than silencing it. Findings it rejects are recorded, so it is not asked the same question every turn. Also fixes a latent hazard this would have made routine. OpenShard runs tail recovery, which truncates, so a CLI opening a store the server is mid-append to could cut off the chunk being written -- the reader destroying the writer's data. Added a read-only open that skips recovery and opens O_RDONLY, and pointed every read-only command at it, including `fathom query`, which had the same problem already. The nudge's cost figure counted each finding separately, so a set of them could claim more money than the window ever spent: $12.52 against a window costing $7.94. Now counted once per trace. claude/ ships the skill and the hook snippet with an installer. The snippet is printed rather than applied, because a script should not blindly edit a settings file that may already have hooks in it, and a mangled settings.json silently disables everything in it.
2.8 KiB
name, description
| name | description |
|---|---|
| insights | Show cost findings from Fathom about your own Claude Code usage — repeated workflows worth turning into a script or throwaway skill, context being paid for twice, and spend that produced nothing. Use when the user runs /insights, or says "show my insights", "what is my Claude usage costing", "any patterns in how I use Claude", or follows up on a "You've got insights on your Claude usage" notification. |
insights
Report what Fathom has found in the user's own agent traces.
What this is
Fathom watches Claude Code sessions and looks for cost patterns: sequences repeated often enough to be worth a script, context paid for more than once, and calls that failed and produced nothing. This command shows what it found.
The analysis is already computed — Fathom does it in the background. This command reads it. Do not re-analyse anything yourself, and do not go reading the user's traces to form your own view: the findings come with the evidence behind them, and your job is to relay them, not to redo them.
Steps
1. Get the findings.
fathom insights
If fathom is not on PATH, try ~/work/fathom/fathom or ask where it lives.
Flags worth knowing:
fathom insights --json— the full analysis, if you need to read fieldsfathom insights --new— only what has not been reported beforefathom insights --reset— mark everything unreported again
2. Relay what it says.
Lead with the finding that has the most money attached. For each one worth mentioning, give:
- what the pattern is, in one line
- what it cost, and how many times it happened
- the suggestion Fathom already wrote
Keep it short. Three findings well explained beats eleven listed.
3. Offer the obvious next step, once.
For a crystallize finding, the next step is usually writing the small script or skill that collapses the sequence. Offer to do it — but only offer. The user knows things about their work that neither you nor Fathom does, and a pattern that looks mechanical may exist for a reason.
If they accept, write it as something disposable. These patterns belong to whatever they are working on now, not forever.
What not to do
- Do not moralise about spend. The findings are observations, not a scolding. "This ran 33 times and cost $1.64" is the whole point; "you should be more careful" is not.
- Do not invent numbers. Every figure comes from the command's output. If you want to say something the output does not support, do not say it.
- Do not open the browser unless asked. The terminal output is the point of this command; the UI at localhost:3000 is there if they want to dig in, and worth mentioning once at the end.
When there is nothing
Say so plainly and stop. A quiet week is a good result, not a failure of the tool, and there is nothing to pad.