codex-session-manager

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Codex Session Manager

Codex会话管理器

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.

Codex将会话记录存储为JSONL文件，路径为

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

。归档会话可能存储在

~/.codex/archived_sessions/*.jsonl

路径下。使用内置管理器可列出候选会话，或将会话导出为包含摘要、时间线、消息文本和关联工具调用详情的Markdown记录。

默认输出文件夹：

~/.codex/session-markdown

。导出前需告知用户该路径，若用户指定了自定义输出文件夹也需提及。

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.

若用户表述明确，可根据其措辞选择模式；否则需在导出前请用户选择：

完整模式：导出所有匹配的会话。适用于归档、备份、广泛搜索或“转换所有会话”的请求。
指定模式：先列出候选会话，请用户选择其中一个，再仅导出该会话。

可从任意目录运行：

bash

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

实用选项：

```
--mode full
```
：导出所有匹配的会话，这是默认模式。
```
--mode specific --list-candidates
```
：打印编号候选表，不执行导出。
```
--mode specific --pick N
```
：从同一筛选后的候选列表中导出第N个候选会话。

--include-archived

：同时扫描

~/.codex/archived_sessions

路径。

```
--project <text>
```
：仅导出包含该文本的日期/项目键对应的会话。
```
--session <text>
```
：仅导出ID或文件名包含该文本的会话。
```
--since YYYY-MM-DD
```
：仅导出修改日期为该日期或之后的会话。
```
--limit N
```
：导出最近修改的N个匹配会话。
```
--include-tool-details-inline
```
：将完整工具负载嵌入主会话Markdown中，而非存储在附属文件中。

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.

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

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

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

当用户需要单个Codex会话、不确定所需会话或要求在转换前检查近期会话时，使用此流程。

运行候选列表命令。默认使用
```
--limit 20
```
，除非用户要求不同数量。

bash

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

若用户提供了日期、会话ID片段或归档提示，需通过相同筛选条件传递：

bash

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

向用户展示编号的候选行。候选表包含修改时间、日期/项目键、短会话ID、当前工作目录（cwd）以及首个用户提示片段。
用户选择编号后，使用完全相同的筛选条件和
```
--pick N
```
重新运行脚本。

若用户已提供精确会话ID或唯一片段，当存在歧义时，先运行

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

。仅当候选列表仅有一个匹配项时，使用

--pick 1

执行导出。

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.

导出器会生成以下文件结构：

text

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

每个会话Markdown包含：

摘要：源路径、键、会话ID、当前工作目录（cwd）、时间戳、事件/消息/工具数量，以及首个用户提示片段。
若存在工具调用或结果，会关联工具详情文件。
时间线：会话元数据、用户/助手/开发者消息、推理摘要、工具调用和工具输出。
内置简短工具摘要，默认将完整JSON负载存储在附属文件中。

Workflow

工作流

Confirm the source folder. Default to
```
~/.codex/sessions
```
; add
```
--include-archived
```
when the user asks about archived sessions.
Ask the user to choose full mode or specific mode if they did not already make the choice.
Confirm or announce the output folder. Default to
```
~/.codex/session-markdown
```
.
For full mode, run the manager script with any needed filters.
For specific mode, list candidates, get the user's chosen number, then export with
```
--pick
```
.
Report the number of sessions exported, output index path, and any parse warnings.

确认源文件夹。默认使用
```
~/.codex/sessions
```
；当用户询问归档会话时，添加
```
--include-archived
```
参数。
若用户未明确选择模式，请其选择完整模式或指定模式。
确认或告知输出文件夹。默认使用
```
~/.codex/session-markdown
```
。
对于完整模式，运行管理器脚本并添加所需筛选条件。
对于指定模式，列出候选会话，获取用户选择的编号，再使用
```
--pick
```
参数执行导出。
报告导出的会话数量、输出索引路径以及任何解析警告。

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.

会话记录数据属于隐私内容，可能包含提示词、文件内容、命令输出、意外粘贴到聊天中的机密信息以及工具结果。
请勿删除或修改原始
```
.jsonl
```
文件。
对于大型会话，优先使用附属工具详情文件。内嵌工具负载会导致Markdown难以搜索和加载。