How Am I Doing (HAID)
Score, visualize, and coach your Claude Code sessions — from the transcripts already on your machine.
You already have the data. Every Claude Code session you've ever run is sitting in
~/.claude/projects/ as a transcript — what you asked for, what the agent did, every file it
read and wrote, every token it spent. HAID turns that pile into three things:
- One number you can track and rank — how much you achieved per token spent, placed against a calibrated reference ladder of real code changes.
- A visualization of where the work and the tokens actually went — a time-layered bus diagram you can read like a subway map of your session.
- A coaching report that tells you what to do differently next time, with cited evidence from your own transcripts — never a confident guess.
Everything runs locally, against transcripts you already have. No instrumentation, no account, nothing leaves your machine unless you explicitly opt in.
Quickstart
Two pieces: the haid CLI (the engine — stdlib-only, zero dependencies) and the Claude Code
plugin (the driver — a skill that runs the pipeline for you).
pip install haid
Then, inside Claude Code:
/plugin marketplace add dv-hart/haid
/plugin install haid@haid
Start a new session and just ask: "how am I doing?" (or invoke /haid-report). Claude
runs the full pipeline — metrics → tag → episodes → score → why → report — and presents your
coaching report. That's it.
Want a taste before involving a model at all? This is free, instant, and fully deterministic:
haid metrics --project ~/path/to/some/project --days 30
What it costs
HAID is free and local. The haid CLI never calls a model itself — the model-judgment
steps (scoring, tagging, investigation) run inside your own Claude Code session as
subagents, so they draw on the plan you already pay for, and the transcripts never leave the
room.
- A full coaching report on a big project (a 30-day window, dozens of sessions) uses roughly 20% of a 5-hour usage window on a Claude Max (5×) plan — that's the recommended tier. Smaller projects cost proportionally less.
- The zero-cost paths —
haid metricsand the--digest-onlyreport — are fully deterministic and never touch a model. Start there if you're budget-shy.
🏆 The leaderboard
Every analyzed window of work gets a single value score:
value = Σ achievement ÷ Σ normalized tokens
— how much you got done, per token spent. That one number is what you track run over run, and it's what the opt-in community leaderboard ranks. The board is:
- Default-off and local-first. Viewing uploads nothing:
haid rankdownloads the public distribution and computes your percentile client-side. - Summary-only when you do submit.
haid submitposts a signed score summary — per-axis positions, the value figure, token totals, ladder/config version hashes. Never your transcripts, diffs, or prompts (a leak check refuses anything path- or title-shaped). - Zero-backend and tamper-evident. Submitting opens a GitHub PR against a separate
data-only repo (
dv-hart/haid-benchmark); identity comes free from the PR author, and the merged, append-only log is rendered by GitHub Pages → the public board.
It's deliberately trust-but-verify, low-stakes — a self-reported board, labeled as such, with a plausibility check as the only gate. The board is young: submit a score and you're among the first on it. See ADR-0005.
The big idea: an achievement ladder, not a token counter
A token count tells you what you spent. It says nothing about what you got. HAID's core idea is to measure achievement relatively, by placing your work against a fixed, calibrated reference ladder of real code changes — then dividing by what it cost.
achievement = volume^0.5 · Difficulty · Cleanliness
value = achievement ÷ normalized-token cost
- Volume — deterministic surviving lines in the final diff, weighted by file kind (hand-written logic > config > generated). Sub-linear, so a small excellent change beats a big mediocre one.
- Difficulty — not lines of code. An LLM judge places your diff on a reference ladder by asking "what fraction of working engineers could produce THIS correctly?" — explicitly ignoring size and surface sophistication. Calibration-validated (Spearman ρ ≈ 0.87 vs. an expensive full pairwise sort). See difficulty-ladder.md.
- Cleanliness — a parsimony placement against its own ladder ("achieves the purpose with less unnecessary complexity?"), a steep penalty that stops LOC-padding from buying score. See cleanliness-ladder.md.
- Cost — tokens weighted by type and model tier into a single normalized-token unit (relative effort, not a dollar bill), always reported with the full per-type/per-tier breakdown.
Achievement is scored on the final artifact, judged as if a human handed it to you cold — it has nothing to do with how many tokens it took. That decoupling is the whole design: a flawless-looking session that burned a fortune on a tiny, unoriginal change is a bad ratio, and HAID will say so. The axes are reported separately and never collapsed, so the score is always auditable. Method and calibration: scoring-rubric.md.
The visualization
The score's companion is a self-contained HTML visualization of the window — a time-layered bus diagram with the agent spine down the middle, files in the gutters (left = reads in, right = writes out), color by file, width by token volume, and per-episode achievement badges from the same scoring run. Opens in any browser, no server:
haid viz --project ~/path/to/project --days 30 --scores out/report/scores.json
Same substrate, two views: where the work went and where the tokens went. Fat buses, re-touch clusters, and retry loops jump out visually before you read a single number. Design in visualization.md.
The coaching report
The score tells you where you stand; the report tells you what to change. HAID runs two orthogonal passes over the session graph:
- User-anchored pass — catches misalignment. Works backward from your messages; corrections are ground truth ("no, I meant…", "that's wrong").
- Signature-scanning pass — catches silent inefficiency: redundant re-reads, retry loops, re-touched lines, unused context — objective, reasoning-free waste signatures.
Flagged hotspots are investigated by per-anchor agents that cite their evidence and hedge their remedies, then matched against a vetted treatment catalog. The guiding constraint everywhere: a tool that confidently misdiagnoses is worse than nothing, so the bar is cite-or-say-unknown (trust-discipline.md). The two passes are complementary — one finds where the agent did the wrong thing, the other where it did the right thing wastefully (architecture.md).
Install notes
HAID is on PyPI — stdlib-only, no dependencies, Python ≥ 3.10:
pip install haid
haid --help
On Ubuntu/WSL without a venv, a user install works fine (ensure ~/.local/bin is on PATH):
python3 -m pip install --user haid
Where to install: HAID reads transcripts from ~/.claude/projects/ on the machine where
the sessions ran. If you use Claude Code inside WSL, install HAID inside WSL too. (A
Windows-side install can still reach WSL transcripts via UNC --session paths like
//wsl.localhost/Ubuntu/home/<user>/.claude/projects/<slug>/*.jsonl, but --project
discovery won't cross the boundary.)
Plugin details: the plugin ships the haid-report skill
plus a SessionStart hook that checks the haid CLI is on the PATH and prints an install
hint if it's missing. If you'd rather not install a plugin, you can copy the skill by hand:
mkdir -p ~/.claude/skills/haid-report
cp .claude/skills/haid-report/SKILL.md ~/.claude/skills/haid-report/
(Working inside this repo, the skill is already active — it's a project skill here.)
How it works under the hood: one session graph
Everything above is computed from a single data structure: a graph of the session(s). Turns and tool-calls are nodes; edges capture responds-to, reads, and produces relationships. Build the graph once and every feature falls out as an operation on it — "why did you do X?" is a backward traversal to X's trigger; "where did the tokens go?" is a weighting over the same nodes; achievement is a placement of the net diff it produces. The pipeline is stdlib-only and deterministic up to the model-judgment boundaries:
- Session parsing (
src/haid/session/) — forest-aware JSONL parsing: dedup, branch/rewind classification, subagent stitching, overflow resolution, SQLite parse-cache. - Session graph (
src/haid/graph/) — L0 spine + L1 action/IO graph (reads/produces/edits fromstructuredPatch), signatures, per-timeline scoping. - Waste metrics (
src/haid/metrics/) —rereads,retries,retouched,unused_context; one rule each, as benchmarkable token-rates vs. a per-scope baseline. - Bridge (
src/haid/bridge/) — reconstructs a window's net code diff from the transcript alone (replay, no git) plus its normalized-token cost. - Scoring (
src/haid/scoring/) — the relative achievement/cost value scorer (difficulty + cleanliness placement, volume, cost, value combiner), calibration-validated. - Intent / Episodes / Why / Report (
src/haid/{intent,episodes,why,report}/) — message tagging, the git-free PR-proxy grouping, the cited investigation pass, and the compositor.
The haid CLI never calls a model itself. The full pipeline is driven by Claude Code
through the skill: the CLI writes a job manifest at each model boundary, and the skill tells
Claude how to fulfill it with subagents and resume. Design:
session-graph-design.md. The whole chain is validated on real
transcripts (python -m pytest); see plans/roadmap.md.
What this is not
Not another token counter. Raw usage accounting is already well covered by ccusage and similar. HAID's entire value lives one layer up — in scoring, diagnosis, and coaching: telling you not what you spent, but how much you achieved per token and how to get better.
Documentation map
| Doc | What's in it |
|---|---|
| docs/vision.md | The full concept, goals, and the canonical test case |
| docs/architecture.md | The two-pass method and how the pieces fit |
| docs/scoring-rubric.md | Achievement vs. cost — the relative value verdict |
| docs/difficulty-ladder.md | The validated difficulty scorer (reference ladder + placement) |
| docs/cleanliness-ladder.md | The cleanliness/parsimony scorer (reference ladder + placement) |
| docs/axis-calibration-playbook.md | Self-contained recipe to calibrate a new scoring axis |
| docs/treatments.md | The remedy catalog matched mechanically in haid report |
| docs/visualization.md | The time-layered bus diagram (left-in/right-out, bundled) |
| docs/session-graph-design.md | Node/edge taxonomy, episodes, the two core operations |
| docs/detectors.md | Detector catalog + waste metrics as graph queries |
| docs/intent-taxonomy.md | Two-axis message classification + purpose timeline + drift |
| docs/metrics-output-schema.md | The haid metrics --json contract |
| docs/claude-code-data-format.md | Verified Claude Code on-disk data reference |
| docs/trust-discipline.md | Cite-or-unknown, hedging, no-traceable-origin |
| docs/decisions/ | Architecture Decision Records (ADRs) |
| plans/roadmap.md | Phased delivery plan |
| plans/community-benchmark.md | The opt-in self-reported leaderboard design (ADR-0005) |
Repository layout
HAID/
├── README.md # you are here
├── docs/ # design & reference documentation (decisions/ = ADRs)
├── plans/ # roadmap + active design notes (shipped build-logs in plans/archive/)
├── src/haid/ # implementation
│ ├── session/ # parse: forest model, subagents, overflow, cache
│ ├── graph/ # L0 spine + L1 IO graph (incl. Bash read/write parsing)
│ ├── metrics/ # the four waste metrics + baseline + `haid metrics`
│ ├── window.py # the multi-session analysis window
│ ├── bridge/ # transcript→(diff, usage) reconstruction
│ ├── scoring/ # relative value scorer (difficulty/cleanliness/volume/cost/value)
│ ├── intent/ # move × work-type message tagging (`haid tag`)
│ ├── episodes/ # session→episode grouping + per-episode scoring
│ ├── why/ # per-anchor investigation agents (`haid why`)
│ ├── report/ # digest + composed report + benchmark payload (`haid report`)
│ └── viz/ # self-contained HTML render (`haid viz`)
├── tests/ # session/ graph/ metrics/ scoring/ bridge/ intent/ episodes/ why/ report/
├── hooks/ # plugin SessionStart hook (CLI presence check)
└── scripts/ # baseline/benchmark-pin regeneration + release/consistency guards
The one-time scoring-axis calibration harness and the raw research probes that seeded the docs live on the
archive/experimentsbranch — their validated output already ships insrc/haid/data/, so they're kept for provenance rather than onmain.
License
MIT.
Metadata
Release files for haid 1.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| haid-1.0.1.tar.gz | 231.5 kB | With provenance | Details for haid-1.0.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| haid-1.0.1-py3-none-any.whl | Python 3 | none | any | Details for haid-1.0.1-py3-none-any.whl |
Total release size: 491.6 kB
Release files / haid-1.0.1.tar.gz
| Download URL | haid-1.0.1.tar.gz |
|---|---|
| Size | 231.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
cc99a951e272e44001968d4547d625d6a93a668609dcb3dc6bdf8a0f6cf9ea71
|
|
BLAKE2b-256 checksum How to use checksums |
9751de5611a590bfb087c81f975b7e9e13c0b8885187649e4fba10ca7c85fe53
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 6, 2026.
Transparency logRelease files / haid-1.0.1-py3-none-any.whl
| Download URL | haid-1.0.1-py3-none-any.whl |
|---|---|
| Size | 260.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
bfa765a96c1619dff2982d21952e05d7bc593a7fb86ca67be05097f0aca54399
|
|
BLAKE2b-256 checksum How to use checksums |
9a5d0b26468f398b147b71966a7df224fd5979f62daa23e69e0f9a61da8e0779
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 6, 2026.
Transparency logSecurity for haid 1.0.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for haid-1.0.1.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 6, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.