# Codex CLI Session Auditor

## PURPOSE
The episode's sponsor segment introduces "the refreshed **Codex CLI**. A new full screen look. Keep tabs on your agents. **Fork a conversation into a separate work tree.** And now talk to your terminal." Teams that adopt that workflow immediately lose track of what their agents actually did. This project is a Click + Pandas command-line auditor that ingests Codex CLI session logs (JSONL, one event per line), then reports per-session token use, which sessions were *forked* into separate worktrees, and which agents are still "open tabs" (idle, unfinished).

## WHY THIS MATTERS
The transcript treats the CLI as a multi-agent cockpit, not a single chat. Once several agents run in parallel and conversations get forked, cost and drift become invisible. Auditing is the operational discipline that keeps a multi-agent terminal honest — the same instinct as "consult your existing side projects before starting another."

## HOW TO BUILD
1. `pip install -r requirements.txt` (Click, Pandas, Rich).
2. Accept a `--sessions` directory of `*.jsonl` files; each line is `{"ts", "session_id", "agent", "event", "tokens", "worktree", "forked_from"}`.
3. Flatten every file into one Pandas DataFrame with a `session_file` column.
4. Implement three subcommands and print Rich tables:
   - `summarize` — tokens and events per session.
   - `worktrees` — sessions that were forked, grouped by `worktree` path.
   - `open-tabs` — sessions with no terminal `close`/`done` event.
5. Add `--json` to emit machine-readable output for CI.

Key snippet — parse + group:

```python
def load(sessions_dir: Path) -> pd.DataFrame:
    rows = []
    for path in sorted(sessions_dir.glob("*.jsonl")):
        for line in path.read_text().splitlines():
            if line.strip():
                rows.append({"session_file": path.name, **json.loads(line)})
    if not rows:  # allow the tool to run with no real logs yet
        return pd.DataFrame(SAMPLE_EVENTS)
    return pd.DataFrame(rows)
```

## WHEN TO USE IN PRODUCTION
Use it in CI to fail a PR when agent sessions exceed a token budget, or as a nightly ops report across a team's shared worktrees. It fits any tool that emits append-only JSONL (agent runs, build logs, eval traces). **Do not** use it for high-cardinality real-time dashboards — Pandas loads everything into memory; that belongs in a warehouse or the Streamlit project in this set. Do not use it as an audit trail for security if the logs are mutable — write-once storage is required first.

## HOW IT HELPS STUDENTS
Students learn log-schema design, defensive parsing of messy JSONL, real Pandas groupby/aggregation, and packaging a genuine multi-subcommand CLI with options, help text, and exit codes — the exact skills needed to make agent activity observable.

## STARTER CODE
See `starter/main.py` for the Click group, the JSONL loader with a deterministic sample fallback, and the three reporting subcommands.
