0.13.1

agentrecap

Get deeper insights into your local coding agents beyond cost.

Generate a local HTML report from your Codex, Claude Code, OpenCode, pi, and Oh My Pi sessions.

uvx agentrecap
# or 
npx agentrecap
# or
pnpx agentrecap
# or
bunx agentrecap

If you do not have uvx or pipx installed, clone the repository and run it with Python:

git clone https://github.com/bansalarnav/agentrecap.git
cd agentrecap
python3 -m venv .venv && .venv/bin/pip install .
.venv/bin/python -m agentrecap.cli

The local virtual environment keeps agentrecap and its dependencies separate from your existing Python installation.

Overview

agentrecap only reads your session data and writes its report to a separate output directory. It will not modify your existing environment or any existing session data.

By default, agentrecap reads active and archived sessions from ~/.codex, Claude Code sessions from ~/.claude/projects, OpenCode sessions from ~/.local/share/opencode, pi sessions from ~/.pi/agent, and Oh My Pi sessions from ~/.omp/agent, then writes the report to ~/.agentrecap/reports/<timestamp>/index.html. When it finishes, it asks whether you want to open the report in your browser. Use --open to open it immediately without the prompt.

agentrecap \
  --codex-input /path/to/codex/home \
  --claude-input /path/to/claude/projects \
  --opencode-input /path/to/opencode/data \
  --pi-input /path/to/pi/agent \
  --omp-input /path/to/omp/agent \
  --since 2026-01-01 \
  --until 2026-06-30 \
  --dir /path/to/project \
  --output-dir /path/to/report \
  --title "My agent usage report"

Use --since and --until to limit the analysis by local calendar date. Both dates are inclusive, and either flag can be used on its own. Omit both flags to analyze all available sessions.

Use --dir /path/to/project to include whole sessions that started in that directory or accessed files beneath it, including reads. The path must be an existing directory. --dir works with date filters, recording, and the live server. Matching uses working directories and file paths recorded in session logs; accesses without a recorded path cannot be inferred.

Recording new sessions

Run start to build a report from sessions created after recording begins:

agentrecap start

Keep the command running while you work, then press q or Ctrl+C to stop and build the report. Activity added to a session that already existed when recording began is not included.

Add --server to serve the captured report after recording stops. The server keeps refreshing those captured sessions without adding sessions created later.

Keeping a report running

--server builds the report and then keeps serving it at http://127.0.0.1:8973/ instead of exiting:

agentrecap --server --port 8973 --refresh-minutes 30

Once it is listening, it prints a clickable URL and asks whether to open it in your browser, the same way a one-shot run does; --open opens it without the question. The analysis reruns every 30 minutes (--refresh-minutes) into the same output directory, so the URL stays stable and the page reloads itself once a new report is ready. The page also gets a Rerun analysis button for refreshing it on demand. The server binds to localhost only, and a failed rerun leaves the previous report in place. Press Ctrl+C to stop it.

The report includes:

• Headline recent and all-time estimated API costs alongside usage metrics.
• Codex, Claude, OpenCode, pi, and Oh My Pi comparisons.
• Model usage, cache ratios, reasoning-token metrics, and monthly estimated API costs.
• Run-duration, response-gap, thread-length, token, cache, and tool-call charts.
• Human-readable, metadata-only CSV files under the report's data/ directory, including estimated lines added and removed in loc_usage.csv.

By default, the generated report includes only metadata. Use --with-transcript to include recorded messages, reasoning, and tool inputs and outputs in threads.csv. The HTML report stays metadata-only. The CSV adds text, tool_input, and tool_output columns. Strings remain readable, and structured values use JSON inside each cell. Transcript exports follow the same date, directory, and recording filters as the report. The flag also works with --server. Transcript content is included as recorded and may contain private text or file contents. Thread, run, event, agent, and tool-call identifiers are hashed before they are written.

Use --compressed to save the transcript CSV as threads.csv.gz for a smaller file to commit to GitHub. It works with or without --with-transcript, including recording and server mode. The report reads the compressed file directly. CSV files under data/ stay uncompressed.

agentrecap --with-transcript --compressed

Cost estimates

For cost estimation, agentrecap uses the pricing catalog from models.dev.

Every request is priced before model and month totals are aggregated. Estimates distinguish uncached input, cache reads, five-minute cache writes, one-hour cache writes, unclassified cache creation, output, and separately priced reasoning when available. Generic models.dev context tiers are selected from each request's complete input footprint, so model-specific 200K, 256K, 272K, and future thresholds can be honored. A bounded fallback supplies the former Anthropic long-context rates for logged Sonnet 4 and 4.5 calls over 200K before Anthropic retired that 1M-context beta on April 30, 2026.

Explicit historical fast/priority metadata uses the provider's fast-mode price from models.dev; default is treated as standard. When a historical record has no speed metadata, it remains unknown and is estimated at the standard API rate as a clearly marked fallback—today's local configuration is never applied retroactively. Claude's raw top-level costUSD, when present, is retained only as reported_cost_usd provenance. All report cards, tables, monthly totals, and displayed exports use the independently calculated estimated_cost_usd.

These are API-equivalent token estimates, not ChatGPT, Codex, Claude, or Claude Code subscription spend or credit consumption. They do not include negotiated discounts, batch pricing, or provider/platform charges not represented in the logs. Unknown model IDs and fast modes without an explicit catalog price remain unpriced rather than receiving a guessed rate.

Development

The project requires Python 3.10 or newer and uses uv for dependency and environment management.

uv sync
uv run agentrecap --help

To generate a report from local session data while developing:

uv run agentrecap --output-dir ./report

Build the source distribution and wheel with:

uv build