# agent-coverage

![screenshot](screenshot.png)

This repo does two things:

1. `main.py` parses a Codex or Claude Code session into file/line coverage.
2. `frontend/` is a static viewer for exploring that coverage against a local repo checkout.

The output is a task tree with command-level coverage entries shaped like `path:start:end`.

## What It Is For

If an agent ran commands like:

```sh
sed -n '120,180p' src/app.ts
nl -ba src/parser.py | sed -n '40,90p'
```

this project turns that session history into structured JSON so you can answer:

- Which files did the agent actually read?
- Which exact line ranges mattered?
- Which user task, subagent, or commentary node led to that read?

## Repo Layout

- [`main.py`](/home/nine/Documents/agent-coverage/repo/main.py): session parser and coverage generator
- [`frontend/`](/home/nine/Documents/agent-coverage/repo/frontend): no-build browser UI for the generated JSON

## Parser Usage

Requirements:

- Python 3
- `codex` CLI installed if the session includes commands the local parser cannot resolve on its own

Run it on a session file:

```sh
python main.py --session-file /path/to/session.jsonl
```

Or resolve a saved session by id:

```sh
python main.py --session-id abc123
```

By default the script writes `coverage_by_request.json` in the current directory.

Session id lookup checks:

- `~/.codex/sessions`
- `~/.claude/projects`

## Frontend Usage

From the repo root:

```sh
cd frontend
python -m http.server 8000
```

Then open `http://localhost:8000` and load:

- the repo you want to inspect
- the coverage JSON generated by `main.py`

The frontend is plain HTML/CSS/JS. No build step.

## Notes

- The parser handles a useful subset of shell reads directly, including `sed -n 'start,endp' file` and `nl -ba file | sed -n ...`.
- When a command cannot be resolved deterministically, `main.py` falls back to `codex exec` to fill in missing ranges and then validates the result.
- The frontend works best in Chromium-based browsers because it uses the directory picker API when available.

For UI details and the accepted JSON shapes, see [`frontend/README.md`](/home/nine/Documents/agent-coverage/repo/frontend/README.md).