---
name: codex-session-to-md
description: "Convert a Codex CLI session transcript to Claude-readable markdown. Use when user says 'codex session', 'convert codex', 'codex转md', provides a Codex session UUID, or wants to review a past Codex conversation. Searches ~/.codex/sessions/ by ID fragment."
argument-hint: [session-id-or-fragment]
allowed-tools: Bash(*), Read, Write
---

# Codex Session to Markdown

Convert a Codex CLI session JSONL transcript to a readable markdown file.

## Session ID

User provided: **$ARGUMENTS**

## Steps

1. **If no session ID provided**, list recent sessions:
   ```bash
   python ./codex_session_to_md.py --list -n 20
   ```
   Show the list and ask the user which session to convert.

2. **Find and convert** the session:
   ```bash
   python ./codex_session_to_md.py "$ARGUMENTS"
   ```
   - If multiple matches, show them and ask user to be more specific.
   - If no matches, suggest `--list` to browse available sessions.

3. **Read and summarize** the output markdown file. Show:
   - Session metadata (cwd, timestamp, model)
   - Number of messages
   - A brief summary of what the conversation covered (first few user messages)

4. **Offer to show the full transcript** if the user wants to read it.

## Notes

- Session files are stored at `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`
- The UUID in the filename is the session ID
- Partial UUIDs work (e.g. `019e6829` matches `019e6829-4f2b-7de1-b9f7-ee507b5e5e59`)
- Output defaults to `./<session-uuid>.md` in the current directory
- Use `-o <path>` to specify a custom output path