Codex Session Manager

Overview

~/.codex/sessions/YYYY/MM/DD/*.jsonl

~/.codex/archived_sessions/*.jsonl

~/.codex/session-markdown

Quick Start

• Full mode: export all matching sessions. Use this for archive, backup, broad search, or "convert all sessions" requests.
• Specific mode: list candidate sessions first, ask the user to pick one, then export only that session.

python3 /path/to/codex-session-manager/scripts/manage_codex_sessions.py

• --mode full

  : export all matching sessions. This is the default.

• --mode specific --list-candidates

  : print a numbered candidate table and do not export.

• --mode specific --pick N

  : export the Nth candidate from the same filtered candidate list.

• --include-archived

  : also scan

  ~/.codex/archived_sessions

  .

• --project <text>

  : only export date/project keys containing this text.

• --session <text>

  : only export sessions whose id or filename contains this text.

• --since YYYY-MM-DD

  : only export sessions modified on or after this date.

• --limit N

  : export the N most recently modified matching sessions.

• --include-tool-details-inline

  : embed full tool payloads in the main session Markdown instead of sidecar files.

Specific Mode Candidate Flow

1. Run a candidate list command. Use

   --limit 20

   by default unless the user asks for a different count.

python3 /path/to/codex-session-manager/scripts/manage_codex_sessions.py \
  --mode specific \
  --list-candidates \
  --limit 20

1. If the user gave a date, session id fragment, or archive hint, pass it through the same filters:

python3 /path/to/codex-session-manager/scripts/manage_codex_sessions.py \
  --mode specific \
  --list-candidates \
  --since 2026-06-01 \
  --include-archived \
  --limit 20

1. Present the numbered candidate rows to the user. The candidate table includes modified time, date/project key, short session id, cwd, and first user prompt excerpt.
2. After the user chooses a number, rerun with the exact same filters and

   --pick N

   .

--mode specific --session <id-or-fragment> --list-candidates

--pick 1

Output Layout

~/.codex/session-markdown/
├── index.md
└── <date-or-archive-key>/
    ├── index.md
    ├── <session-id>.md
    └── tool-details/
        └── <session-id>.tools.md

• Digest: source path, key, session id, cwd, timestamps, event/message/tool counts, and first user prompt excerpt.
• Linked tool details file when tool calls or results exist.
• Timeline: session metadata, user/assistant/developer messages, reasoning summaries, tool calls, and tool outputs.
• Short tool summaries inline, with full JSON payloads in the sidecar file by default.

Workflow

1. Confirm the source folder. Default to

   ~/.codex/sessions

   ; add

   --include-archived

   when the user asks about archived sessions.
2. Ask the user to choose full mode or specific mode if they did not already make the choice.
3. Confirm or announce the output folder. Default to

   ~/.codex/session-markdown

   .
4. For full mode, run the manager script with any needed filters.
5. For specific mode, list candidates, get the user's chosen number, then export with

   --pick

   .
6. Report the number of sessions exported, output index path, and any parse warnings.

Notes

• Treat transcript data as private. It can contain prompts, file contents, command output, secrets accidentally pasted into chat, and tool results.
• Do not delete or modify original

  .jsonl

  files.
• Prefer sidecar tool details for large sessions. Inline tool payloads can make Markdown hard to search and load.