ClaudeMap

harness-profiler

A Claude Code plugin that records every skill, subagent and tool call through hooks and gives you a profiler's view — a call tree with durations, a UML-style diagram of contexts, and per-context token costs

SDKs & Toolingprofilerhooksobservabilityplugintokens

harness-profiler shows what a non-trivial Claude Code (or Codex, not yet supported) setup — skills, subagents, memory files — actually does underneath. It records only what Claude Code itself reports through hooks (after every tool call, on subagent stop, session start, and around compaction), appending one JSON line per event to .harness-profile/<session-id>.jsonl at the git root; the first write adds the folder to .git/info/exclude so traces stay out of commits. The tree command turns a session into a profiler view: one line per skill or subagent call with UTC start time, a duration bar on a square-root scale, and the tokens that context spent (new input, cached input, output), plus --verbose for every tool call; --format html renders the same data as a UML sequence diagram where each bar is a context and colors distinguish fresh contexts from forks. /show-profile publishes the trace in-session (as a private claude.ai artifact on the web, or in your local browser). Install paths: /plugin marketplace add afurmanov/harness-profiler plus /plugin install for CLI sessions, or a committed hook via npx -y github:afurmanov/harness-profiler init claude for cloud sessions, which copy hooks into .claude/ and let local sessions start recording at once; doctor reports which Node runs the hook and whether a committed copy is stale. The tool is one dependency-free file plus a launcher and a page template; the hook runs async and exits 0 so a broken trace never breaks a session. Tokens come from Claude Code's transcripts under ~/.claude/projects/; nothing leaves the machine unless you run /show-profile in a cloud session. Codex is not supported yet — the README documents exactly what its hooks can and cannot see.

What it does

  • Profiler view of an agent harness: call tree with UTC times, square-root-scaled duration bars, and per-context token columns (new / cached / out) straight from Claude Code's transcripts
  • UML-style sequence diagram (--format html) where each bar is a context — subagents and context:fork skills get their own color; inline skills appear as diamonds in the caller
  • Low-touch recording: hooks append JSON lines to .harness-profile/<session-id>.jsonl, run async, always exit 0, and the folder lands in .git/info/exclude so traces stay out of commits
  • Two install paths: plugin marketplace for CLI sessions, or npx ... init claude to commit the hook for Claude Code on the web; doctor verifies the Node, hook and stale copies
  • /show-profile publishes in-session (private claude.ai artifact on web sessions, local browser otherwise); CLI tree takes session prefixes, --branch and --verbose

When to use it

Use when a composed setup (orchestrator skills, validators, forked contexts) is slow, expensive or not doing what you expect and you need to see which skill ran where, in which context, at what token cost. Skip it if you only run single-session prompts — there is little structure to profile.

Getting started

Claude Code CLI:

/plugin marketplace add afurmanov/harness-profiler
/plugin install harness-profiler@harness-profiler
Run /reload-plugins, or start a new session

Claude Code on the web (commit the hook instead):

npx -y github:afurmanov/harness-profiler init claude
git add .claude/harness-profiler .claude/skills/show-profile .claude/settings.json && git commit -m "Record tool calls with harness-profiler"

Check from a repository you work in:

npx -y github:afurmanov/harness-profiler doctor

Text tree of the newest session:

npx -y github:afurmanov/harness-profiler tree

Requires Node 18+ and git (not on npm; npx runs it straight from GitHub).

Things to know

The trace knows token counts, not content, and the transcript format is undocumented — if it changes, token numbers disappear rather than go wrong. Inline skill calls cost into their caller and cannot be separated; file reads and edits done through Bash (cat, sed, python one-offs) show up as Bash calls. The hook is started by sh: on Windows it needs Git Bash or WSL, otherwise nothing records. Codex is not supported yet: hooks need /hooks trust, failed shell commands report as normal calls, skills register only when a command reads their SKILL.md or runs their scripts, and two concurrent spawns can swap in the tree. MIT. 40 stars as of writing (2026-11-21).

Repository

afurmanov/harness-profiler

Charted

Related on the map

  • The open Agent Skills standard — SKILL.md folders any agent can load, governed by the Agentic AI Foundation since 2026-10-22.

    • official
    • spec
    • agent-skills
    • standard
  • Harness Bridge

    SDK / Tool

    A local launcher that points Claude Code and seven other coding harnesses at any OpenAI-, Anthropic- or Responses-compatible endpoint — without editing a single config file.

    • launcher
    • local-models
    • cli
    • menu-bar
  • Claude for Siri

    SDK / Tool

    Answers macOS Spotlight and Siri prompts with your signed-in Claude Code account — an experimental macOS 27 model-delegation provider.

    • macos
    • siri
    • spotlight
    • model-delegation