Harness Doctor

Harness Doctor

Harness Doctor is the fleet view over the agent's own history. It mines the last $days of agent transcripts across every project on this machine and answers one question — where did the wall-clock, the tokens, and the repeated corrections go, and what change stops the bleeding. It reads the whole session tree, workflow and subagent transcripts included, and turns it into five fact tables plus a ranked fix list. The waste is invisible from inside any single session: a command that costs 9 seconds is nothing until you see it ran 1,400 times.

This is a user-invoked command (/harness-doctor); the window in days arrives as $days. When it is empty, use 30 — the templates below already do.

How to run

The auditor is zero-dependency with no build step, shipped twice: scripts/audit.ts and scripts/audit.py. They take the same flags and write the same tables — pick whichever runtime exists. Detect with command -v node bun python3 on macOS/Linux, or where node bun python on Windows, then run from the skill's scripts/ dir:

node audit.ts --days "${days:-30}"        # Node >= 22.18 (native TS type-stripping)
bun run audit.ts --days "${days:-30}"     # Bun
npx tsx audit.ts --days "${days:-30}"     # older Node, no install needed
python3 audit.py --days "${days:-30}"     # no JS runtime at all

The summary goes to stdout; progress goes to stderr, so node audit.ts --format json > facts.json stays clean. In md mode the last stdout line is the work dir holding the fact tables — --no-tables writes none and prints none.

Three more flags carry the work: --project <substr> narrows to project dirs matching the substring (repeatable); --top <n> sets rows per ranking (default 15), but --format md clamps every table to 25 rows whatever --top says, so ask for a deeper table with --format json; --format json emits the machine shape documented in reference/stats.md. The rarer ones — --out, --root, --no-tables, --no-redact, --pricing — are in the CLI table in reference/stats.md. --no-redact writes prompts and command output verbatim, secrets included: pass it only when the user asks for it by name.

If the script does not run here

The fact tables are the contract, not the script. When neither runtime works, or transcripts live outside ~/.claude/projects, write your own extractor to the five tables in reference/stats.md, then continue from Read the summary, then dig unchanged. Every angle downstream reads those five files and nothing else.

When a full scan is too slow, rerun with --days 7 and say in the report that the window is 7 days, so every number is read against the right denominator.

Read the summary, then dig

The script does the counting. Your job starts after it: read the summary, pick the angles the numbers point at, then go into the fact tables for the specifics the summary only ranks.

reference/angles.md holds seven angles, each with what to compute from which table, what a good finding reads like, and the trap that angle carries. Read it before you dig. Each summary section routes to one:

Fan out one agent per angle when the window holds more than ~500 sessions (window.filesScanned) or the user asked for a full audit: give each the work dir path, its angle's section of reference/angles.md, and the instruction to recompute its own numbers before reporting, then merge. Below that, work the three angles with the largest numbers in the summary yourself.

Dig with jq, rg, or a throwaway script over the JSONL — the tables are line-oriented and sized for it. Move data with code: filter and aggregate on disk, and read only the rows you will quote.

Verify before you report

Every number in the report is one you recomputed or read off a table. Not one you inferred, not one you carried across a unit change, not one an angle agent handed you without a source. Say which table and which filter produced it.

Two failures from a real run of this analysis, both of which passed a casual read:

• Spend reported as saving. The headline claimed a large dollar figure would be recovered, when the figure was the estimated total cost of the window. A saving is a difference between two numbers you can both name: before, after, and the change that moves one to the other.
• The skill's own text counted as user complaints. A keyword scan for correction words matched harness-generated turns and quoted instructions echoing through transcripts, reporting 41 complaints where 24 were real. Count only rows with human: true in user-msgs.jsonl, and re-read every correction you are about to quote in its own row: the bucket matched a phrase, it did not read the turn.

What to produce

A ranked, copy-pasteable fix list, ordered by impact over effort, not grouped by angle. Each fix carries the measured number it is based on and the exact text to apply: the package.json script line, the CLAUDE.md sentence, the settings.json entry, the command to run. "Consider caching your builds" is not a fix; "typecheck": "tsc -b --incremental" next to "bun run typecheck ran 412 times, 3.9h total, median 34s" is.

One row per fix, in this shape:

1. Make typecheck incremental : bun run typecheck ran 412 times, 3.9h total tool time, median 34s (commands, bash.jsonl). Add to package.json: "typecheck": "tsc -b --incremental", and *.tsbuildinfo to .gitignore. Effort: one line. Applies to ~/Code/app only.

A fix with no number attached does not ship. Cut it or go measure it.

Done when every fix row names its number, the table that number came from, and the exact text to apply — and every summary section that ranked something either produced a fix or carries one line saying why its numbers are not waste.

Close by widening the window

The corpus is capped by what the harness kept. Claude Code deletes session files older than cleanupPeriodDays at startup — default 30, minimum 1 (settings docs). So a 90-day audit on a default install quietly reads 30 days, and next quarter's audit has no more history than this one.

As the last step of every run, after the fix list, read ~/.claude/settings.json and report the retention window:

• Key absent. Say the default is 30 days, that every angle in this audit sharpens with a longer history, and offer the exact edit — "cleanupPeriodDays": 180 in ~/.claude/settings.json (365 suits a heavy user who wants a year to mine). Name the cost in the same breath: transcripts are uncompressed JSONL, and a heavy user accumulates gigabytes a year. Apply it only when the user says yes.
• Key present. State the value in one line and move on.

Cross-check the setting against the data either way. Compare the days asked for against the age of the oldest row in sessions.jsonl (min(start)). When the oldest transcript is much younger than the window, the corpus is truncated — say so, because every total in the report then sits on a shorter denominator than the user assumes.

reference/retention.md holds the same facts for the other harnesses — which ones keep transcripts forever, which delete, where each stores them — for when the user asks whether their other agent is losing history too.

Guardrails

• Propose, then ask. CLAUDE.md, settings.json, and package.json are user-owned and durable. Show the change and its number, offer to apply it, and edit the file only after an explicit yes to that change.
• Absence of evidence is not evidence of absence. This is one machine, one local history, possibly pruned or compacted. Report "I found no trace of X in the scanned window", never "you don't do X".
• Check the fix is not already on disk. Read the projects section and the repo before recommending a script, a rule, or a setting that already exists there; a duplicate rule is worse than none.
• durSec is approximate and cost is estimated. What each measures is in reference/stats.md; say it once, near the first table that uses either, then state numbers plainly. Hedging every line makes the whole report unreadable.
• The fact tables contain real prompts and real command output. They land on disk at the work dir printed on the last stdout line, when tables were written at all. Redaction is best-effort and on by default; --no-redact writes secrets verbatim and is only for a user who asked for it. Tell the user where the files are and that deleting them is theirs to do.
• Quote sparingly. Short evidence lines only. The report is a fix list, not a transcript excerpt.

Notes

• Claude Code transcripts only in v1. Codex rollouts (~/.codex/sessions/**/rollout-*.jsonl) carry a different line shape and are skipped. Say so when a user asks about a Codex session.
• Large corpora take minutes. Thousands of transcripts and gigabytes of JSONL are normal; progress lines on stderr show where it is.