Metadata-Version: 2.5
Name: agentrecap
Version: 0.13.1
Summary: Analyze local Codex, Claude Code, OpenCode, pi, and Oh My Pi sessions
Requires-Python: >=3.10
Requires-Dist: certifi>=2024.8.30
Requires-Dist: flask>=3.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: matplotlib>=3.10.0
Requires-Dist: numpy>=2.2.0
Requires-Dist: pandas>=2.3.0
Description-Content-Type: text/markdown

# agentrecap

> Get deeper insights into your local coding agents beyond cost.

![An agentrecap report showing usage metrics and charts](docs/agentrecap-report.png)

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

```bash
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:

```bash
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.

```bash
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:

```bash
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:

```bash
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.

```bash
agentrecap --with-transcript --compressed
```

## Cost estimates

For cost estimation, `agentrecap` uses the pricing catalog from [models.dev](https://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](https://docs.astral.sh/uv/) for dependency and environment management.

```bash
uv sync
uv run agentrecap --help
```

To generate a report from local session data while developing:

```bash
uv run agentrecap --output-dir ./report
```


Build the source distribution and wheel with:

```bash
uv build
```
