MasterSelects includes a local Codex session monitor for answering:
- what the user asked
- how many model calls the turn triggered
- how many input, cached input, output, reasoning, total, and cache-adjusted tokens were reported
- which Git commit and dirty state were observed while the AI worked
- which turns were long-running, open, stale, or unusually expensive
The monitor reads Codex JSONL session logs from ~/.codex/sessions, filters sessions whose session_meta.cwd is inside this repository, and writes local analysis artifacts to .codex-usage/.
One-shot report:
npm run codex:usageContinuous watcher:
npm run codex:usage:watchStop a watcher started with the provided PowerShell launcher:
npm run codex:usage:stopMonitor output:
.codex-usage/turns.jsonl
.codex-usage/turns.deduped.jsonl
.codex-usage/sessions.json
.codex-usage/report.md
.codex-usage/state.json
When using scripts/start-codex-usage-watch.ps1, it also creates:
.codex-usage/watcher.pid
.codex-usage/watcher-launch.json
.codex-usage/watcher.out.log
.codex-usage/watcher.err.log
.codex-usage/ is ignored by Git because it contains local conversation metadata.
The monitor also accepts --repo, --sessions-root, --out, --poll-ms, and --stale-minutes; use --include-answer-text only when storing full visible assistant text locally is appropriate.
Codex logs token usage per model call in event_msg entries with payload.type = "token_count".
The monitor groups all last_token_usage entries after a user message until the next user message or end of the session file. It marks the turn completed on task_complete or a final_answer, but continues recording later token events for that current turn until the next user message.
The monitor deduplicates turns with the same question, answer preview, model-call count, and token totals. It keeps raw turns in turns.jsonl, marks duplicates with dedupe, and writes representative turns to turns.deduped.jsonl. report.md uses the deduped data by default and shows the raw inflation separately.
Important fields:
| Field | Meaning |
|---|---|
inputTokens |
Full prompt/context tokens sent to the model |
cachedInputTokens |
Input tokens served from prompt cache |
uncachedInputTokens |
inputTokens - cachedInputTokens |
outputTokens |
Generated output tokens reported by Codex |
reasoningOutputTokens |
Reasoning subset when Codex reports it |
visibleOutputTokensEstimate |
outputTokens - reasoningOutputTokens |
totalTokens |
Reported inputTokens + outputTokens |
cacheAdjustedTotalTokens |
totalTokens - cachedInputTokens |
reasoningOutputTokens appears to be included in outputTokens, so the monitor does not add it a second time.
The watcher stores Git snapshots in .codex-usage/state.json:
- branch
- HEAD commit
- commit subject and timestamp
- dirty status and short status output
- first observation and last recorded change time per turn
scripts/start-codex-usage-watch.ps1 starts a hidden watcher, writes .codex-usage/watcher.pid, and avoids starting a second process when that PID belongs to codex-session-monitor.mjs. It also records launcher status in .codex-usage/watcher-launch.json.
Open .codex-usage/report.md after running the command. The most useful tables are:
Most Expensive Turns: sort by total tokensRecent Turns: chronological review of latest questionsOpen or stale turns: visible in the totals for incomplete work
For deeper analysis, load .codex-usage/turns.jsonl into a script or spreadsheet and group by git.lastGit.shortHead, status, toolUsage.tools, or question text patterns.