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.