home / skills / dcjanus / prompts / codex-session-reader

codex-session-reader skill

safe

This skill reads a single Codex session by thread id, returning full or sliced turns to support viewing, summarizing, or analysis.

npx playbooks add skill dcjanus/prompts --skill codex-session-reader

Review the files below or copy the command above to add this skill to your agents.

Files (3)

SKILL.md

1.8 KB

---
name: codex-session-reader
description: 读取 Codex 的单个 session/thread；当已知 thread id 且需要查看或摘要会话内容时使用。
---

只读查看单个 Codex session/thread 的 skill，底层通过 `codex app-server` 官方接口读取。

默认输出全部 turns；如只想看局部，可用 `--turns` 传 0-based、接近 Python 的切片表达式。

## Quick start

```bash
cd skills/codex-session-reader
./scripts/codex_session_reader.py read <thread-id>
```

## 何时使用

- 用户要求查看某个 Codex thread/session。
- 用户给出 thread id，希望读取完整上下文。
- 需要把某个 Codex 会话内容转成可继续摘要或分析的 Markdown。

## 常用命令

```bash
./scripts/codex_session_reader.py read <thread-id>                    # 读取完整 thread
./scripts/codex_session_reader.py read <thread-id> --preview-only     # 只看 preview 和元信息
./scripts/codex_session_reader.py read <thread-id> --turns :5         # 前 5 个 turns
./scripts/codex_session_reader.py read <thread-id> --turns -5:        # 后 5 个 turns
./scripts/codex_session_reader.py read <thread-id> --turns 10:-1      # 从第 10 个到倒数第 1 个之前
./scripts/codex_session_reader.py read <thread-id> --turns 13         # 只看第 13 个 turn
./scripts/codex_session_reader.py read <thread-id> --turns 13:15      # 读取第 13 到第 14 个 turns
./scripts/codex_session_reader.py read <thread-id> --format json      # 输出 JSON
```

## 输出约定

- 默认输出 `markdown`，适合继续交给 Codex 阅读或摘要。
- 默认输出全部 turns。
- `--format json` 输出 app-server 返回的结构化结果，便于脚本处理。
- 若发生区间裁剪，JSON 会额外包含 `truncated` 字段说明实际输出的是哪一段。
- `--turns` 不支持 step；`1:10:2` 这类表达式会报错。

Overview

This skill reads a single Codex session (thread) using the official codex app-server API. It returns the session turns in human-friendly Markdown by default and can emit structured JSON for automated processing. You can slice the output to focus on a subset of turns using a Python-like, 0-based slice expression.

How this skill works

The tool calls the codex app-server to fetch a session by thread id, then formats the response as Markdown or JSON. By default it outputs all turns; a --turns argument accepts slice expressions (start:stop) to return a specific range. When JSON output is requested, the raw app-server structure is preserved and a truncated field is added if the returned segment is a slice.

When to use it

You have a specific Codex thread id and need to inspect the full conversation.
You want to extract a subset of turns for targeted review or further processing.
You need Markdown-ready conversation content for summarization or handoff to another tool.
You want machine-friendly JSON for script-driven analysis or archiving.

Best practices

Prefer Markdown output for manual review and follow-on summarization tasks.
Use --turns with 0-based slice notation to limit data returned and speed up retrieval.
Request --preview-only to view metadata and preview content before fetching full turns.
Use --format json when feeding results into other automation or storage pipelines.
Avoid step values in slices; only start:stop forms are supported.

Example use cases

Read a complete session for context before continuing an interrupted conversation.
Fetch the last N turns with a negative slice to quickly see recent exchanges.
Produce Markdown of a thread to hand off to a summarizer or review tool.
Export session structure as JSON for indexing, searching, or audit logs.
Preview metadata to confirm thread identity before downloading the full transcript.

FAQ

How do I view only metadata or a preview of the thread?

Use the --preview-only flag to display thread metadata and the preview without downloading all turns.

Can I use stepping in the --turns slice like 1:10:2?

No. Step values are not supported. Use start:stop slices or single indices.