1---
2name: codex-session-browser
3description: Inspect local Codex conversation history, locate which repo or worktree a session belongs to, and extract plain user/assistant messages from Codex JSONL logs without tool calls. Use when someone asks where Codex stores sessions, wants the latest prompts or replies for a project, needs to parse `~/.codex/sessions`, or wants only the text conversation for a repo such as `forgedemy`.
4---
5 
6# Codex Session Browser
7 
8Use the bundled parser instead of hand-grepping raw JSONL.
9 
10Preferred entrypoint:
11 
12- `python3 scripts/codex_sessions.py list --repo /abs/repo/path`
13- `python3 scripts/codex_sessions.py messages --repo /abs/repo/path --limit-sessions 3 --tail 10`
14 
15## What this skill knows
16 
17- Codex sessions live under `~/.codex/sessions/YYYY/MM/DD/*.jsonl`.
18- The repo or worktree is recorded in `session_meta.payload.cwd` near the top of each file.
19- Plain conversation text is easiest to extract from `event_msg` records:
20  - `user_message` -> user prompt text
21  - `agent_message` -> assistant text output, with `phase` such as `commentary` or `final_answer`
22- Tool calls and tool outputs live in other record types such as `response_item` with `function_call`, `function_call_output`, or `custom_tool_call`; ignore them unless the user explicitly asks for tool traces.
23- Some sessions may not have `event_msg` conversation entries. In that case the parser falls back to `response_item` records whose payload is a plain `message` from `user` or `assistant`.
24 
25## Workflow
26 
271. Identify the target repo or session.
28 
29- For one repo/worktree, use `--repo /absolute/path` for exact `cwd` matching.
30- If the exact path is unknown, use `--cwd-contains partial-name` first.
31- If the user already knows a session id or filename fragment, use `messages --session <id-or-path>`.
32 
332. List candidate sessions first.
34 
35- Run `python3 scripts/codex_sessions.py list --repo /abs/repo/path --limit 10`
36- This shows session timestamp, file path, repo `cwd`, message count, and short previews of the last user and assistant text.
37 
383. Extract plain conversation text.
39 
40- Run `python3 scripts/codex_sessions.py messages --repo /abs/repo/path --limit-sessions 1 --tail 8`
41- This prints only user/assistant text messages, not tool calls.
42- Increase `--limit-sessions` to inspect multiple recent sessions.
43- Use `--tail 0` to print the full text conversation for each matched session.
44 
454. Narrow the assistant output when needed.
46 
47- Use `--assistant-phase final_answer` when the user wants only final answers.
48- Use `--assistant-phase commentary` when the user wants progress updates instead.
49- Use `--role user` or `--role assistant` to isolate one side.
50 
515. Use JSON output when another script or agent will consume the result.
52 
53- `python3 scripts/codex_sessions.py list --repo /abs/repo/path --json`
54- `python3 scripts/codex_sessions.py messages --repo /abs/repo/path --limit-sessions 3 --tail 12 --json`
55 
56## Examples
57 
58Find the latest `forgedemy` Codex sessions:
59 
60```bash
61python3 scripts/codex_sessions.py list \
62  --repo /home/latand/Projects/forgedemy \
63  --limit 5
64```
65 
66Pull the last few prompts and replies for that repo, without tool calls:
67 
68```bash
69python3 scripts/codex_sessions.py messages \
70  --repo /home/latand/Projects/forgedemy \
71  --limit-sessions 2 \
72  --tail 8
73```
74 
75Only show final assistant answers from the latest matched session:
76 
77```bash
78python3 scripts/codex_sessions.py messages \
79  --repo /home/latand/Projects/forgedemy \
80  --assistant-phase final_answer \
81  --tail 4
82```
83 
84Inspect one exact session by filename fragment:
85 
86```bash
87python3 scripts/codex_sessions.py messages \
88  --session 019cf134-ec89-77d3-a78f-1710bc2a8c03 \
89  --tail 0
90```
91 
92## Reporting back
93 
94When summarizing results for the user, include:
95 
96- the matched repo path or session id
97- the session timestamp
98- the last relevant user prompt(s)
99- the assistant reply text the user actually cares about
100- a note that tool calls were excluded unless the user asked for them
101