Create offline reports from coding-agent conversations: complete messages, evidence-linked analysis, per-model token and cost comparisons, and a zoomable timeline with local day/night shading. Supports Copilot CLI, Claude Code, Codex, Cursor exports, and Replit conversation exports.
See the example: HTML report, standalone player, or PDF.
Use Python 3.12 or later. Install the package and its Chromium renderer in a virtual environment:
Windows PowerShell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install agent-session-insights
python -m playwright install chromium
macOS/Linux
python3 -m venv .venv
source .venv/bin/activate
python -m pip install agent-session-insights
python -m playwright install chromium
On Linux, missing browser system libraries may require
python -m playwright install --with-deps chromium and system-install privileges.
Report commands check rendering dependencies before processing sessions or
launching an agent.
The installed agent-session-insights command works from any directory.
python -m agent_session_insights accepts the same arguments. For a source
checkout, use python review.py after installing requirements.txt; see the
maintainer guide.
If Windows activation is unavailable, invoke the virtual environment's
.\.venv\Scripts\python.exe with the module or checkout entry point directly.
agent-session-insights repo --repo C:\Source\my-project
This selects the newest matching session, freezes its logs, launches its
native harness headlessly for reviewed annotations, then generates and verifies
the report. The harness CLI must be on PATH and signed in; normal model charges
apply. Only the selected evidence is reviewed. Use --noagent for measured
accounting and replay without qualitative annotations or model calls.
Automatic discovery supports Copilot, Claude, and Codex. It matches recorded repository/working-directory metadata in the current user's native history stores, not project mentions in messages, and excludes native subagents. Missing or malformed metadata limits discovery; Cursor/Replit require explicit exports.
Native stores under your home are .copilot\session-state, .claude\projects,
.codex\sessions, and .codex\archived_sessions. Home-directory overrides honor
COPILOT_HOME, CLAUDE_CONFIG_DIR, and CODEX_HOME.
List the matching sessions before choosing:
agent-session-insights discover --repo C:\Source\my-project
agent-session-insights repo --repo C:\Source\my-project --session copilot:SESSION_ID
Repeat --session to combine selected IDs, or use --all for every match.
For a combined report, the first selected session's harness reviews the evidence.
--harness filters the histories searched; it does not choose a different
reviewer for those histories.
| Option | Purpose |
|---|---|
--repo PATH |
Required local repository directory. |
--session ID |
Select an ID or harness:ID ; repeat for multiple sessions. |
--all |
Combine all matches; mutually exclusive with --session . |
--harness NAME |
Search only copilot ,claude , orcodex . |
--root PATH |
Override the native history directory; requires --harness . |
--output PATH |
Override the report destination. |
--noagent |
Skip the harness and qualitative annotations. |
--logs-only |
Save selected raw logs as session-logs.zip in the output directory; no analysis, agent, or report. |
--timezone ZONE |
IANA report timezone; default America/Los_Angeles . |
--pricing PATH |
Override the bundled, dated retail API pricing card. |
For example, combine only Copilot sessions without launching an agent:
agent-session-insights repo --repo C:\Source\my-project --harness copilot --all --noagent
All commands have --help with command-specific examples.
agent-session-insights repo --repo C:\Source\my-project --all --logs-only --output .\collected-logs
This writes .\collected-logs\session-logs.zip without running analysis, calling
a model, or requiring Chromium/Playwright. The same selection rules apply:
newest matching session by default, repeated --session for specific sessions,
or --all for every match; --harness and --root also work.
Omit --output to use the normal default destination directory.
The ZIP contains byte-for-byte copies of the selected history files under
logs, a manifest.json with source hashes, and discovery.json. It does not
include auxiliary session files or subagent histories. Extract it and use
run --manifest with the extracted manifest to generate a report later.
Report-only --pricing, --timezone, and --noagent do not trigger analysis;
the timezone is saved in the manifest for later use.
Existing destination files are left untouched, and an existing
session-logs.zip is refused; choose another output directory or move the
previous ZIP. Raw logs are not redacted and may contain credentials,
private conversation text, and local paths. Review before sharing.
The default destination is agent-session-reports\<repo-name> under your
current working directory, not automatically inside the repository passed to
--repo.
Successful report commands print the absolute paths of report.html,
report.pdf, and player.html. Open the HTML files directly; no server is needed:
Start-Process .\agent-session-reports\my-project\report.html
On macOS, use open instead of Start-Process. Reports include supporting
accounting, normalized events, coverage, verification, frozen pricing, and
private source snapshots. Repository reports also save discovery.json and a
reusable manifest.json, plus annotations.json when agent-reviewed.
Reports and players share bold blue typography, white light-mode surfaces, and
a navy dark mode. They follow your system theme; embedded replay and log panes
follow the surrounding report. Append ?scoutTheme=light or ?scoutTheme=dark
to a report or standalone player URL to override the system preference.
Overwrite protection: existing reviews require Overwrite? [y/N]?
confirmation; only y or yes proceeds. An empty answer or closed stdin cancels.
Directories containing unrelated files or selected inputs are refused.
Confirmed replacement removes the previous report before generation, so use a
fresh --output directory when you need to retain it if generation fails.
Privacy: outputs contain conversation text and private raw snapshots.
Credential and shared-session URL redaction is best effort; review files before
sharing or publishing them. This repository ignores the default report directory;
keep outputs out of version control yourself in other workspaces. POSIX outputs
use directory mode 0700 and file mode 0600. Windows outputs inherit the parent
directory's NTFS ACLs; Python's chmod does not set those ACLs.
Interpretation limits: retail API-equivalent estimates are not invoices. Frozen rates may be historical; unknown models or missing total usage are unpriced, not free. Missing cache counters can produce labeled estimates and ranges, not verified cache hits. Different workloads and cache use prevent per-model totals from being an efficiency benchmark. Timeline activity is not measured working time; day/night shading uses 06:00-18:00 daytime in the report timezone, not astronomical sunrise/sunset.
A missing or failed harness is an error, not a silent fallback to --noagent.
Completion requires verified artifacts and intact snapshots, not merely a zero
harness exit status.
| Command | Input | Result |
|---|---|---|
discover |
--repo PATH , or--harness NAME --root PATH |
JSON inventory; no report or agent. |
repo |
--repo PATH |
Complete report with agent review unless opted out. |
prepare |
--manifest FILE --output DIRECTORY |
Frozen evidence and measured analysis; no HTML/PDF/player or agent. |
run |
--manifest FILE --output DIRECTORY |
Complete report using existing annotations if supplied; never launches an agent. |
Use a report's saved manifest to render its frozen sources, annotations, and pricing into a different, empty directory:
agent-session-insights run --manifest .\agent-session-reports\my-project\manifest.json --output .\rerendered
Keep the original directory intact: the manifest references files saved beside it. This avoids rereading changing live logs or repeating model interpretation.
Create a JSON manifest for selected history files, including Cursor/Replit exports. Paths are relative to the manifest:
{
"title": "Project review",
"timezone": "America/Los_Angeles",
"sources": [
{"harness": "copilot", "path": "logs\\events.jsonl", "session": "session-id"},
{"harness": "cursor", "path": "chat.md", "session": "export-id"}
]
}
Each source needs harness, path, and session. Supported harness identifiers
are copilot, claude, codex, cursor, and replit. Optional source start
and end values are inclusive, timezone-aware ISO timestamps. Optional
annotations and pricing paths provide reviewed interpretation and a custom
rate card. Without supplied annotations, run labels qualitative interpretation
unavailable.
agent-session-insights run --manifest .\review.json --output .\imported-review
For manual annotation, use prepare, review its stable event IDs and measured
evidence, then create a final manifest referencing the prepared snapshots and
your annotations in the same source order. prepare marks interpretation
pending even if its input manifest contains annotations. This staging is
optional; repo handles it automatically.
See collection contracts for export formats and scoping, analysis rules for accounting limits, and the example rate card for the pricing schema. No report-time network access is needed for token pricing.
For natural-language selection, use the bundled agent-session-insights agent in this repository's workspace and ask:
Make a report for C:\Source\my-project. I want to pick the sessions.
Unlike the CLI's automatic selection, the agent prompts for unresolved session
choices and the output location. Its profile is
.github/agents/agent-session-insights.agent.md; the collect, analyze, and publish
skills are under .github/skills/. You can copy those definitions into another
workspace. Installation does not register agents globally or change personal
settings. See agent contracts for the
annotation-only launcher and interactive workflows.
Clone/download this repository, then run from its root:
agent-session-insights run --manifest .\examples\creation.json --output .\tmp\creation-review
The example uses a scoped, redacted export of the conversation that built this project, reviewed annotations, and frozen historical prices. Rebuilding it needs no agent or model call. Offline copies of the HTML report, player, and PDF are also checked in. Download the HTML files and open them locally; GitHub's file viewer does not run the player.
See the maintainer guide for checkout setup, tests, example provenance, GitHub Pages deployment, and PyPI releases. DESIGN.md contains collection, accounting, privacy, and player contracts. The project is MIT licensed.