Project case study
peek
peek turns the session logs coding agents already write into historical analysis of context, cost, compactions, and configuration changes.
Problem
Coding agents record a large amount of session data, but the raw logs do not readily explain where context went, what a session cost, when compaction changed the working set, or whether a configuration change helped.
Those questions become harder when work spans multiple harnesses with different log formats and usage fields.
Why existing approaches fall short
Native context and usage views are useful during a live session, not for cross-harness historical analysis after it ends.
ccusage already provides cross-harness totals, while Claude-focused visual tools provide deeper views for one harness. Neither combines historical composition, compaction analysis, attribution depth, whole-session diffs, and CLI or JSON output across all three supported harnesses.
Approach and architecture
Read the source of record
Harness adapters read existing local session logs. Exact totals come from each harness's recorded usage fields, while estimated composition is visibly marked and any unlogged residual is named.
Normalize analysis across harnesses
A shared command surface exposes session inventory, context composition, cost attribution, compaction timelines, diffs, and self-contained HTML reports for Claude Code, Codex, and pi.
Test configuration changes with real runs
peek bench runs a trusted task suite under two configurations in isolated git worktrees, executes the suite's verification command, then compares the resulting session logs with the same accounting model.
Proof
- Accounting reconciliation
- The published comparison reports a 0.00% delta against ccusage for every token class and cost at matched scope. Design notes.
- Point-in-time corpus coverage
- The public README records 2,000 real Claude Code sessions, 67,458 turns, and zero parse failures in its committed integration test run. Public proof table.
- Measured cache and A/B results
- The published runs show peek list improving from 6.18 seconds cold to 0.21 seconds warm, and a passing model A/B trial using 19.1% fewer tokens and costing 93.4% less for 1.1 seconds more wall time. Public proof table.
Key tradeoffs
- peek is deliberately historical. It does not replace a harness's live context or usage display.
- Exact totals do not make every composition category exact. Estimates stay marked, and the Codex composition analysis currently reports a 67.4% residual.
- Bench trials call real agents, can cost money, and use worktrees for isolation rather than as a security boundary.
Lessons
- Observability is more trustworthy when exact values, estimates, and unknown residuals are kept distinct.
- Publishing a refuted near-exact composition hypothesis was more useful than preserving a stronger but unsupported claim.
- The same accounting path should power both everyday inspection and experiments so benchmark conclusions remain auditable.