@mstuart/peek

See inside your coding agent's sessions — composition, cost, compactions, and config A/B — across Claude Code, Codex, and pi.

Install · Commands · Proof · Compared to · Bench

peek reads the session logs your coding agent already writes to disk — Claude Code, Codex, pi — and turns them into historical analysis. No live instrumentation, no proxying, no telemetry. Three things make it different:

• Exact totals, never re-tokenized. Every number comes straight from each harness's own usage fields — peek reconciles against ccusage at 0.00% delta, cost included.
• Honest composition. Estimates are marked ~, the unlogged remainder is named ("system prompt + tool schemas + framing") instead of hidden, and a hypothesis that didn't hold up — Codex's "near-exact" composition — is published as refuted, not quietly dropped.
• Config A/B with real agents. peek bench re-runs your own task suite under two configs and diffs the results with peek's own accounting. The demo below is a real run.

Install

Requires Node 20+. Not yet on npm (npx peek-agent is coming); install from source:

git clone https://github.com/mstuart/peek.git && cd peek
npm install && npm run build
node dist/cli.js list

npm install -g github:mstuart/peek also works (it builds on install). Everything runs locally — no telemetry, session data never leaves your machine (SECURITY.md).

harness      session   cwd                     started           turns  tokens     cost  compactions
codex        real-cap  /…/FRd8m1Q7N8L07        2026-08-08 22:13      4   37.5k        —            0
claude-code  sess-com  /Users/you/project      2026-08-01 15:00      3   23.0k    $0.04            1
claude-code  sess-nor  /Users/you/project      2026-08-01 10:00      2    3.4k  $0.0086            0

Commands

Point any command at a session id or path — or omit it to use the most recent. --json everywhere. Real captured output for each lives in docs/examples/.

Command	What it does
peek list	Cross-harness inventory: cost, tokens, compactions. Warm in 0.21s via the totals cache.
peek context	Per-turn context composition for an ended session, residual named honestly.
peek cost	Cost attribution by model/tool/MCP server; --all merges every session, --by narrows it.
peek compactions	The compaction timeline: what shrank, what was discarded, codex window lineage.
peek diff	Composition/cost/config diff of two sessions, or --last N (2–5) across recent runs.
peek report	Self-contained shareable HTML — one session, --diff <a> <b>, or --all for a trends dashboard.
peek bench	Re-run a task suite under two configs with real agents (below).

Proof

Every number is measured, not estimated.

Claim	Measured	Source
Totals reconcile against ccusage	0.00% delta, every token class + cost, at matched scope	docs/DESIGN.md
Real-corpus parse success	100% — 2,000 real Claude Code sessions, 67,458 turns, 0 failures (point-in-time)	test/local.integration.test.ts
peek bench A/B gate	current vs model=haiku: both passed, −93.4% cost, −19.1% tokens	docs/examples/bench-report.txt
peek list cold → warm	6.18s → 0.21s (totals cache, 7,526 hits)	docs/PERF.md
Codex "near-exact" hypothesis	Refuted and published: 67.4% residual measured, not restated as success	docs/DESIGN.md

Compared to

The real bar is native tooling: Claude Code's own /context and /usage do live composition and attribution for free — peek never competes there. peek's edge is historical analysis across three harnesses after a session ends.

	Historical composition	Cross-harness	Compaction analysis	Cost depth	Session diff	CLI + JSON
Native /context + /usage	No	No	No	Live only	No	No
ccusage	No	Yes — totals	No	Totals only	No	Yes
claude-devtools	Yes	Claude Code only	Yes	Per-subagent	No	GUI only
agent-replay	No	Yes — traces	No	No	Step-level	Yes
peek	Yes	Claude Code, Codex, pi	Yes	Per-tool/MCP/subagent	Whole-session	Yes

Stated plainly: ccusage already owns cross-harness cost totals (peek's edge is attribution depth, not totals); claude-devtools already does composition and per-subagent cost trees (but Claude-Code-only, GUI-only). Skip peek if you want live in-session monitoring (use /context), only need cost totals (use ccusage), or only use Claude Code and want a GUI (use claude-devtools).

Bench

Every other command is read-only. peek bench runs agents: it re-runs your task suite under two config variants — a CLAUDE.md/AGENTS.md/settings.json/model overlay, or current — in isolated git worktrees, verified by your test command, then parses each trial's own session log for exact tokens, cost, and compactions. Trials hit the real APIs and cost money; this repo ships the gate's suite at .peek/bench/.

peek bench run --suite .peek/bench --config-a current --config-b .peek/bench/configs/haiku

peek bench — current (a) vs config-b (b)

task        success a   success b   wall Δ           tokens Δ            cost Δ
hello-file  1/1 (100%)  1/1 (100%)  +1.1s (+13.5%)   -15,864 (-19.1%)   -$0.54 (-93.4%)

Both configs passed verify; switching to haiku cut cost 93.4% for +1.1s wall — a real run, not a projection.

Not a sandbox. A worktree is a filesystem convention, not a security boundary — trial agents run with your OS permissions, so only bench task suites you trust. A first-run or changed suite requires explicit trust confirmation (every command shown verbatim, direnv-style); --yes skips the cost estimate but never the trust prompt — only an interactive yes or --trust-suite does. Per harness: claude-code is fully gated (the result above); codex has a runner verified with a real trial but no orchestrated A/B yet; pi is deferred to v2.1.

Status

v1 shipped through a multi-round adversarial design review before implementation; v2 added peek bench, the totals cache, cost --all, pi System B, and the report dashboard. Verified, not just designed: 100% real-corpus parse, a privacy audit, and a full performance profile — the design reference and measured-results ledger are in docs/DESIGN.md, with details in docs/PERF.md and docs/PRIVACY-AUDIT.md.

Known limitations: pi is source-verified only (no real pi data validated yet); Codex composition is measured at a 67.4% residual, not near-exact — see the Codex and pi caveats in docs/DESIGN.md.

License

MIT — see LICENSE.