Skip to main content
skill CX Codex

codex-session-manager — Claude Code skill: export and analyze sessions

codex-session-manager — a skill to work with local Codex session transcripts. Exports sessions to structured Markdown with timelines, tool calls, and archived data.

MIT 199 installs ★ 140 updated 2026-10-19

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add sugarforever/01coder-agent-skills --skill codex-session-manager -a claude-code
Open on GitHub

What codex-session-manager does

codex-session-manager reads JSONL files from ~/.codex/sessions and ~/.codex/archived_sessions, converts them into readable Markdown with session digest, message timeline, and tool call details. The skill operates in two modes: full export of all matching sessions or selection from a candidate list before conversion.

Output goes to ~/.codex/session-markdown with an index, individual session files, and a sidecar for tool payloads. Filter by date (--since), session id fragment, project, or count of recent changes (--limit). By default, tool details live in separate files, but you can embed them directly in Markdown using --include-tool-details-inline.

Transcripts may contain private data—the skill does not delete or modify source .jsonl files.

What it helps with

  • Export Codex sessions to structured Markdown with timeline
  • List and find archived sessions
  • Extract and analyze tool-call history from JSONL transcripts
  • Filter sessions by date, project, or identifier
  • Recover and inspect past conversations from ~/.codex

Example prompts for the agent

  • Export all sessions from the last two days to Markdown
  • Show me the 10 most recent sessions so I can pick one to export
  • Save the session from 2026-06-15 with id matching 'project-alpha' including archived ones

How to install codex-session-manager

1Skills CLI (Vercel)

npx skills add sugarforever/01coder-agent-skills --skill codex-session-manager -a claude-code

2Manually: put the files in place

~/.claude/skills/codex-session-manager/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/codex-session-manager/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about codex-session-manager

How do I install codex-session-manager in Claude Code?

Run npx skills add sugarforever/01coder-agent-skills --skill codex-session-manager -a claude-code, then open ~/.claude/skills/codex-session-manager/SKILL.md to verify.

What does codex-session-manager do?

It converts local Codex JSONL sessions into readable Markdown with timeline, digest, tool-call details, and archive support. You can filter by date, project, or id and choose between full export or single-session mode.

Where are Codex sessions stored and how do I recover them?

Active sessions are in ~/.codex/sessions/YYYY/MM/DD/*.jsonl; archived ones are in ~/.codex/archived_sessions/*.jsonl. Use --include-archived to scan both locations, then pick a session from the candidate list.

Source text

SKILL.md · MIT
---
name: codex-session-manager
description: Manage local Codex session transcripts, including listing candidate sessions, exporting full or selected sessions to organized Markdown, inspecting archived sessions, and summarizing tool-call history. Use when the user asks to scan, parse, archive, inspect, recover, summarize, manage, or convert Codex sessions, `~/.codex/sessions` data, `~/.codex/archived_sessions` data, `.jsonl` transcripts, tool-call history, or hard-to-read Codex conversation logs.
---

# Codex Session Manager

## Overview

Codex stores session transcripts as JSONL files under `~/.codex/sessions/YYYY/MM/DD/*.jsonl`. Archived sessions may also exist under `~/.codex/archived_sessions/*.jsonl`. Use the bundled manager to list candidates or export sessions into Markdown transcripts with a digest, timeline, message text, and linked tool-call details.

Default output folder: `~/.codex/session-markdown`. Tell the user before exporting there, and mention any custom output folder they requested.

## Quick Start

Let the user's wording choose the mode when it is clear; otherwise ask them to choose before exporting:

- 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.

Run from any directory:

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

Useful options:

- `--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

Use this flow when the user wants one Codex session, is unsure which session they need, or asks to inspect recent sessions before converting.

1. Run a candidate list command. Use `--limit 20` by default unless the user asks for a different count.

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

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

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

3. 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.
4. After the user chooses a number, rerun with the exact same filters and `--pick N`.

If the user already gives an exact session id or unique fragment, use `--mode specific --session <id-or-fragment> --list-candidates` first when there is any ambiguity. Export with `--pick 1` only when the candidate list has exactly one match.

## Output Layout

The exporter writes:

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

Each session Markdown includes:

- 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.

© sugarforever · MIT · sugarforever/01coder-agent-skills

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set18

The whole set →
share-reading share-reading drafts social posts about an article, link or set of notes, with a few takes and the source link kept in every one. CX Codex +1 440installs personal-chinese-writing-style personal-chinese-writing-style enforces one set of Chinese typography rules while the agent writes, translates or edits: quote marks, dash, ellipsis, no stray ASCII punctuation. CX Codex +1 408installs fpl-copilot fpl-copilot analyzes Fantasy Premier League statistics, tracks squad drafts, and builds custom match reports in your agent workspace. CX Codex +1 295installs cover-image cover-image — a skill that builds article covers in hand-drawn style. Picks composition and palette from text or lets you set them manually. CX Codex +1 291installs promote-post promote-post generates teaser tweets for published articles using a post link or local file, hooking readers without giving away summaries. CX Codex +1 277installs codex-cli Enables an agent to hand off coding, review, and image generation tasks to OpenAI Codex CLI via non-interactive exec commands. CX Codex +1 237installs claude-session-manager claude-session-manager turns local Claude Code JSONL logs into readable Markdown files with conversation, digest, and tool call history. CX Codex +1 207installs mining-session-skills mining-session-skills analyzes a completed Claude Code session and proposes which skill to create, update, or reuse so similar work runs faster next time. Works with exported markdown from claude-session-manager. CX Codex +1 196installs

Project sponsors

Companies that keep this analytics open