Your first report.
Your next experiment.

Agent Recap 0.1.0 reads local Claude and Codex logs. You choose whether to add an AI review.

Install and run

Requires Node.js 22 or newer. Start with demo data:

npx --yes --package https://agent-recap.pages.dev/downloads/agent-recap-0.1.0.tgz agent-recap serve --demo --open

The package is served directly from this site. The npm package agent-recap has not been published yet. Use the full command above.

For a shorter everyday command, install this version once:

npm install --global https://agent-recap.pages.dev/downloads/agent-recap-0.1.0.tgz
agent-recap serve --demo --open

With Bun:

bunx --package https://agent-recap.pages.dev/downloads/agent-recap-0.1.0.tgz agent-recap serve --demo --open

Download the CLI package · SHA-256 checksums · Download source

Use your own sessions

agent-recap serve --since 7d --open
agent-recap report --since 7d --format html --out week.html
agent-recap report --format json --out week.json
agent-recap report --format md --out week.md

Use these commands after the global installation above. Otherwise prefix them with the same npx --package command. Output files are never overwritten. HTML reports contain a fixed snapshot; use the local server for live filtering.

Sources and filters

Claude uses $CLAUDE_CONFIG_DIR/projects or ~/.claude/projects. Codex uses $CODEX_HOME/sessions or ~/.codex/sessions and supported archive directories. Remote-only sessions are unavailable.

agent-recap serve --provider Codex --since 30d --open
agent-recap report --workspace my-project --out project.html
agent-recap serve --claude-path /path/to/projects --codex-path /path/to/sessions

Days are UTC calendar days, including today. Sources are scanned at startup; restart to refresh. Filtering does not shorten the initial scan. Missing sources and token records are shown as gaps, not zero usage.

Explore and improve

Insights shows a UTC activity heatmap, daily session timelines and tool/model usage. Overview compares the selected period with the preceding equal period. Coaching links patterns to examples and offers editable skill drafts.

agent-recap serve --project /path/to/project --open
agent-recap context --project /path/to/project --out context.json

The optional project inventory checks for instructions, documentation, skills, tests and manifests. It checks presence, not quality. Session spans are recorded intervals, not hours worked. Review skill drafts before installing them.

Use the Agent Recap skill

A skill lets your coding assistant run reports and explain their evidence. Install the CLI first, then download the skill. Inspect SKILL.md before installation.

For Codex on macOS or Linux, these commands download the skill archive and extract into a new skill folder. An existing folder is preserved.

curl -fLo agent-recap-skill.tar.gz https://agent-recap.pages.dev/downloads/agent-recap-skill.tar.gz
mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
mkdir "${CODEX_HOME:-$HOME/.codex}/skills/agent-recap" &&   tar -xzf agent-recap-skill.tar.gz --strip-components=1   -C "${CODEX_HOME:-$HOME/.codex}/skills/agent-recap"

Start a new assistant session and ask:

Use $agent-recap to summarize my last seven days.
Explain the coverage and suggest one experiment.

For Claude Code, put the extracted agent-recap folder in .claude/skills/ inside your project. Other assistants need support for SKILL.md skills. The skill guides the workflow; it does not add new parsers or automatic improvement tracking.

Optional AI review

Set a compatible chat-completions endpoint and model. Supply remote credentials through your shell or secret manager.

export COACH_AI_BASE_URL=https://your-provider.example/v1
export COACH_AI_MODEL=your-model-id
# Set COACH_AI_API_KEY securely for remote services.
agent-recap serve --open

A local model can use an HTTP loopback endpoint, such as http://127.0.0.1:1234/v1, without an API key. Provider and model compatibility varies; no live AI provider has been validated for this release.

agent-recap review --session SESSION_ID --out packet.json
# Inspect the packet before making an external request.
agent-recap review --session SESSION_ID --send --out review.json

The packet contains selected prompts, responses and tool names. It excludes full tool arguments, results and repository context. Redaction cannot catch every secret. AI review is disabled for demo sessions.

Privacy and interpretation

Session files are read-only. Ordinary analysis has no telemetry or automatic AI calls.
The local server binds to loopback. This public website has no session upload endpoint.
Exported reports can include workspace names and source paths. Keep personal exports private.
Tokens are observed usage, not bills. Missing usage affects coverage.
Repeated prompts and cancellations do not prove poor work. Neither activity nor model advice establishes task success.
The website is hosted on Cloudflare, which handles normal web requests. We have added no analytics or account system.

Troubleshooting

No sessions found

Check the Sources view, confirm your assistant stores sessions locally, and set the explicit source-directory flags if needed. Only Claude and Codex are supported today.

The report seems out of date

Restart the CLI to rescan. Confirm the period uses the UTC dates you expect. An exported HTML file is an immutable snapshot.

An output file already exists

Choose a different output filename. The CLI intentionally refuses to overwrite existing files.

Demo/browser and package checks are covered in development. Broader operating-system compatibility and live AI services still need validation.

Your first report.Your next experiment.