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.
72 lines
2.8 KiB
Markdown
72 lines
2.8 KiB
Markdown
---
|
|
name: insights
|
|
description: 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.**
|
|
|
|
```sh
|
|
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 fields
|
|
- `fathom insights --new` — only what has not been reported before
|
|
- `fathom 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.
|