Aleksandr Furmanov's open-source Claude Code plugin records every skill, subagent and tool call through hooks and draws a session as a UML-style sequence diagram, one bar per context, with duration and new, cached and output tokens per context. Its point: once a harness grows to dozens of skills and agents, a run can report PASS while doing redundant work, and only a call tree with costs shows it.
How it works
Capture is a set of async Claude Code hooks; analysis is an offline tree builder over the trace. Everything is one dependency-free Node file (hp.js) behind a POSIX launcher.
Capture.
PostToolUseandPostToolUseFailure(both carryduration_ms, so no Pre/Post pairing),SubagentStop,SessionStart, andPreCompact/PostCompact. Each event appends one JSON line of at most 4,096 bytes to.harness-profile/<session>.jsonlat the git root, a singleappendFileSyncso concurrent hooks don't interleave. The directory is added to.git/info/exclude, so traces stay out of commits.Fail-open. The hook runs
async(about 33 ms per call, mostly Node startup, off the tool's critical path) and always exits 0. Without Node it silently does nothing; adoctorcommand exists to catch that.Parent links by id, not time. A call whose
agent_idmatches another call's returnedagentIdis its child. The author rejected interval containment because a main-context call that runs while a subagent works gets misfiled.Contexts as the unit. A context is one conversation history: main, a fresh subagent or forked skill (
context: fork), or a copy of the parent (the built-inforkagent type). Inline skills are markers inside their caller's context, drawn as diamonds. Copies keep the parent's color; fresh contexts get a new one.Tokens per context, by kind.
new(plain input plus cache writes),cached(cache reads) andout, summed from Claude Code's per-context transcripts under~/.claude/projects/. No price is shown: a single weighted total hides that a copy's tokens are mostly cheap cache reads, and subscription accounting isn't published.Outputs.
tree(text call tree, square-root duration bars),tree --format html(a self-contained sequence-diagram page, no network loads),--verbosefor every Bash, Read, Edit and MCP call, and a/show-profileskill. On Claude Code on the web the hook is committed into.claude/viainit, because cloud sessions only install account-synced plugins, and the page is published as a private artifact before the container is discarded.
Rejected designs worth noting: Perfetto and Gantt or flame timelines (readers mistook overlapping calls for nesting), per-OS binaries (unreadable hooks), fetching the tool on first run (breaks behind cloud network policy), and a Stop hook pushing traces to a side branch.
What it found: a "final" validation that redid everything
The blog post's real case cost up to a minute and 48k new tokens per change, and both runs reported PASS. The task was a small Ruby SDK change (reject a blank API key). The workflow validates twice: after the code change, then again after the agent trims its planning doc to a decision record. The second run is meant to be cheap: the validator consults the trace and reuses any check that passed after the last change to its files, so only the doc checks should rerun.
| Run | Duration | New tokens | Cached tokens | Output tokens |
|---|---|---|---|---|
| First validation | 69 s | 66.7k | 426.4k | 2.9k |
| Final validation | 60 s | 48.0k | 447.0k | 3.2k |
The final run reran the Rails review (14 s, 41.4k new tokens), tests and lint, though only Markdown had changed. The author spotted it visually: two validation bars of near-equal length with identical children. Two root causes: the code was left uncommitted, so the reuse rule saw every Ruby file as changed, and the reuse script crashed under an old system Ruby. The fix was to commit before final validation and run the script under the project's Ruby.
The transferable lesson is the last step: once you know what a healthy trace looks like, encode it as a check-trace skill (ordered skill calls, which calls must run in fresh contexts, no duplicate skill runs per story) and run it after sessions. That turns the profiler from a debugging aid into a behavioural regression test for the harness.
Limits and tradeoffs
The profiler sees only what hooks and transcripts expose, so it shows structure and spend, not content or causality.
Token numbers depend on an undocumented format. Spend comes from Claude Code's transcripts; if their format changes, numbers disappear (by design, rather than go wrong).
Inline skills are invisible as cost centers. An inline skill's tokens merge into its caller's, and where its work ends is not reported. Teams that want per-skill cost must fork skills into their own contexts, which changes behaviour and cost.
Model-level tool calls only. Work done through Bash (
cat,sed, one-off Python), common on the web, appears as Bash calls, so Read/Edit/Grep counts understate file activity.No content. It knows how many tokens a context held, not what they were, so it locates waste but not bloated prompts within a context.
Background agents are messy. They fire
SubagentStopseveral times and hand back viaSubagentHandback; the tool takes the last stop as the end. A trace captured mid-run shows calls asrunning.Codex is unsupported, and the recorded Codex notes explain why it's hard: hooks need explicit trust, failures aren't reported, skills leave no call, and concurrent
spawn_agentcalls can be swapped.Data handling. Traces stay local unless
/show-profilepublishes one in a cloud session; tool arguments and the first line of results are recorded, so a trace can hold sensitive strings.
Versus built-in tracing. A commenter points to Claude Code's OpenTelemetry tracing beta (CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1 plus an OTEL_TRACES_EXPORTER), where subagent spans nest under the parent's tool span. If that holds, OTel is the better fit for fleet-wide dashboards in an existing backend, and harness-profiler's additions are skill boundaries, inline-versus-fork distinction, per-context token kinds, and a zero-infrastructure local page. The two are complementary rather than competing.
On the billing claim. The post says Anthropic moved Claude Enterprise to token billing in April and GitHub moved Copilot in June; it says "reportedly" for the first. The argument does not need it: per-context spend matters for latency and rate limits even on flat plans.
Review checklist
Record a baseline trace of a known-good run for each main workflow before changing skills; diff later traces against it.
Decide which skills must run in a fresh context (validators, reviewers) and assert that in a
check-traceskill; inline-versus-fork is both a correctness and a cost choice.Watch the
newcolumn, not totals: copies of the parent inflatecachedcheaply, while repeated fresh contexts drive real spend.Look for repeated children under sibling bars (the double-validation pattern) and for any reuse or caching rule that depends on git state.
Run
doctorin CI or session start so a missing Node or stale committed hook doesn't silently record nothing.Treat traces as sensitive: they hold tool arguments and result first lines. Keep them excluded from git and think before publishing one.
If you already ship OpenTelemetry, decide which questions each tool answers rather than running both by default.
Related
R099 (Evaluating agents at Amazon): trace-level evaluation of agent runs at production scale; harness-profiler is the single-developer, local version of the same idea.
R064 (SkillEvaluator): measures whether a skill helps; the profiler measures what it costs and whether it ran as intended.
R054 (Harness engineering, eleven coding agents): how harnesses structure sub-agents and context; this tool makes that structure visible in your own setup.
R005 (Second Brain OS): the profiler is an instrument for the loop and harness layers.
Sources
LinkedIn post, Aleksandr Furmanov (2026-11-15) and its comments
afurmanov/harness-profiler README and docs/design.md (MIT)
What Did My Software Factory Just Do?, blog post, 2026-11-15