cxs is a local-first CLI for searching Codex session logs. It is designed for progressive retrieval: find the right session first, then read
docs(skill): 补 current 工作流 / 减薄 SKILL.md / 加 error shape 速查
review 后的最佳实践 follow-up:
- 加 cxs current 子命令工作流 (cli-surface.md / progressive-workflow.md
Scenario 4 / SKILL.md "什么时候用 cxs" 表)。current 直读 Codex state DB,
零索引依赖,适合 sync 没跑过或刚换机器的场景,之前 SKILL.md 完全没教
- failure-cookbook 加 ## state_db_unavailable 段 (列 missing-file /
missing-table / missing-column 三类 message 与处置),并加一张 --json
error shape 速查表 (sync SyncSummary / sync lock-timeout string /
current structured payload 三种形状)
- SKILL.md 减薄至 76 行 (原 166):删与 references 重复的"三步渐进式
检索"命令 / "JSON 模式速查"字段 / "常用排障"完整表;主体只留触发
场景 + 心法 + 链 references
- frontmatter description 合并本机已装版的英文触发词
(last time I / earlier session / previous codex chat / ...) 避免重
install 后丢失英文召回
- install 段重排成"两步":1) CLI 二进制(指 README CLI Install Guide)
2) skill (npx skills add ...);并说明 -a codex 是 Codex agent
runtime,Claude Code/Anthropic 用户应换 -a 取值
skill-sync 时间戳 bump 到 2026-04-27。
同步 ~/.claude/skills/cxs/ 已与 repo 一致 (rsync + diff 确认)。
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Entire-Checkpoint: 0e41f6684198
+129
-136
+45
-135
.agents/skills/cxs/SKILL.md
+45
-135
.agents/skills/cxs/SKILL.md
···
1
1
---
2
2
name: cxs
3
-
description: "用于用户要找本机 Codex 历史会话或 ~/.codex/sessions 上下文：之前、上次、前几天、我记得、我们讨论过、翻旧 session、找那次命令、历史对话、Codex history、previous/earlier/last Codex chat。不要用于当前仓库代码搜索、外部文档、今日提交/日报或当前会话收尾。"
3
+
description: "用于用户要找本机 Codex 历史会话或 ~/.codex/sessions 上下文:之前、上次、前几天、昨天、我记得我配过、我试过、我们讨论过、翻旧 session、找那次命令、历史对话、Codex 历史、session 历史。Also triggers on English: 'last time I', 'earlier session', 'did we already', 'I remember configuring', 'previous codex chat', 'search my codex history'. 不要用于当前仓库代码搜索(Grep)、读当前文件(Read)、外部文档(WebFetch/WebSearch)、今日提交/日报(commit-daily-summary)或当前会话收尾(session-wrap)。"
4
4
---
5
5
6
6
# cxs
7
7
8
-
用 `cxs` 在 `~/.codex/sessions` 里检索旧 Codex 对话。目标是先定位候选 session，再局部扩上下文，最后才翻全页，不要冷启动整批 JSONL。
9
-
10
-
## 安装
11
-
12
-
```bash
13
-
npx skills add catoncat/cxs --skill cxs -g -a codex -y
14
-
```
15
-
16
-
CLI install guide: https://github.com/catoncat/cxs#cli-install-guide
17
-
18
-
这个 skill 只提供 agent 工作流，不安装 `cxs` CLI 本体。若用户询问安装方式，指向 README 的 CLI install guide，并提醒安装或更新 skill 后需要重启 Codex / 开新 session。
19
-
20
-
## 路径前提
21
-
22
-
这个 skill 只包含说明和参考资料，不会把 `cxs` CLI 二进制一起装进你的系统。
23
-
24
-
使用前请满足下面任一条件：
25
-
26
-
- `cxs` 已经在 `PATH` 里
27
-
- 或设置了 `CXS_BIN=/absolute/path/to/bin/cxs`
28
-
29
-
所有命令默认都写成：
30
-
31
-
```bash
32
-
"${CXS_BIN:-cxs}" <subcommand> ...
33
-
```
34
-
35
-
使用前先验证命令面确实是 cxs：
36
-
37
-
```bash
38
-
"${CXS_BIN:-cxs}" --version
39
-
"${CXS_BIN:-cxs}" --help
40
-
```
41
-
42
-
如果 `--version` 没有输出 cxs 版本，或 `--help` 没有列出 `sync/find/read-range/read-page/list/stats/current`，不要继续猜；改用 `CXS_BIN=/absolute/path/to/bin/cxs`，或先让用户完成 CLI install guide。
43
-
44
-
这样可以同时兼容：
45
-
46
-
- 你自己安装到 `PATH` 的 `cxs`
47
-
- 本地 checkout 里的 `bin/cxs`
48
-
- 其他自定义路径
49
-
50
-
## 什么时候用 cxs
8
+
用 `cxs` 在 `~/.codex/sessions` 里检索旧 Codex 对话。心法:**先定位候选 session,再局部扩上下文,最后才翻全页**——不要冷启动整批 JSONL。
51
9
52
-
| 场景 | 用什么 | 原因 |
53
-
| --- | --- | --- |
54
-
| 用户问“之前 / 上次 / 我记得 / 我们讨论过” | `cxs` | 目标是历史 session，不是当前 repo |
55
-
| 用户给了旧项目名、cwd、时间窗口 | `cxs list` 起手 | 先按 `cwd/since` 缩范围比全文搜更稳 |
56
-
| 用户问“最近本项目 / 这个 repo 做过什么讨论” | `cxs list --cwd <current-repo>` 起手 | 先圈出当前 repo 里的候选 session，再做主题判定 |
57
-
| 用户记得某个旧命令、旧报错、旧方案关键词 | `cxs find` 起手 | 先拿 `sessionUuid + matchSeq` |
58
-
| 当前仓库代码/字符串搜索 | 代码搜索工具 | 那是代码库，不是 session 历史 |
59
-
| 当前文件或已知路径阅读 | 文件读取工具 | 不需要走 session 索引 |
60
-
| 外部文档/网页/产品资料 | WebFetch / WebSearch | 不在本机 Codex 历史里 |
61
-
| 今日提交/日报 | commit-daily-summary | 目标是 git，不是 session |
62
-
| 当前会话收尾 | session-wrap | 目标是本轮工作，不是旧对话 |
10
+
## 安装(两步)
63
11
64
-
## 什么时候不要用 cxs
12
+
**1. 装 cxs CLI 二进制**(本 skill 不带 binary,只是 agent 工作流):
65
13
66
-
- 用户要搜当前 repo 代码、配置、测试、文档
67
-
- 用户要查外部网站、官方文档、最新信息
68
-
- 用户要总结今天提交、项目日报、当前会话
69
-
- 你已经知道具体 JSONL 文件路径且只需直接读原文
70
-
- 没有 `sessionUuid` 时，不要一上来 `read-page`
71
-
72
-
## 前置
73
-
74
-
- 先用 `stats --json` 看 `dbPath`、`lastSyncAt`、`sessionCount`
75
-
- 如果 `stats --json` 提示索引不存在，先跑 `sync`
76
-
- 用户明确说“最近那次”“我刚做过”，但 `lastSyncAt` 很旧或 `find`/`list` 零结果时，先跑 `sync`
77
-
- `sync` 默认严格模式；任一文件失败都会非零退出且不提交半截索引
78
-
- 只有用户接受部分成功时才加 `--best-effort`
79
-
- 从别的 cwd 调用时，若默认 db 不对，显式传 `--db`
80
-
81
-
## 三步渐进式检索
82
-
83
-
1. 如果用户给了项目名、cwd、时间窗，先缩范围：
14
+
详见 README 的 [CLI Install Guide](https://github.com/catoncat/cxs#cli-install-guide)。安装后做一次 sanity:
84
15
85
16
```bash
86
-
"${CXS_BIN:-cxs}" list --cwd hammerspoon --since 2026-04-15 --json
17
+
"${CXS_BIN:-cxs}" --version # 应输出 cxs 版本号
18
+
"${CXS_BIN:-cxs}" --help # 应列出 sync/find/read-range/read-page/list/stats/current
87
19
```
88
20
89
-
如果用户说“本项目 / 这个 repo”，把 `<cwd>` 直接换成你当前工作目录路径。
21
+
如果 `cxs` 不在 PATH 里,设 `export CXS_BIN=/absolute/path/to/bin/cxs`。
90
22
91
-
2. 常规入口永远先 `find`，不要冷启 `read-page`：
23
+
**2. 装 skill**:
92
24
93
25
```bash
94
-
"${CXS_BIN:-cxs}" find "cf tunnel" --json -n 5
95
-
```
96
-
97
-
先看这些字段：
98
-
99
-
- `results[].sessionUuid`
100
-
- `results[].matchSource`
101
-
- `results[].matchSeq`
102
-
- `results[].cwd`
103
-
- `results[].startedAt`
104
-
- `results[].matchCount`
105
-
- `results[].summaryText`
106
-
- `results[].snippet`
26
+
# Codex agent runtime
27
+
npx skills add catoncat/cxs --skill cxs -g -a codex -y
107
28
108
-
3. 拿最像的候选做局部扩窗：
109
-
110
-
```bash
111
-
"${CXS_BIN:-cxs}" read-range <sessionUuid> --seq <matchSeq> --before 4 --after 8 --json
29
+
# Claude Code / Anthropic agent runtime — 把 -a codex 换成对应 runtime,或省略
112
30
```
113
31
114
-
4. 如果你已经锁定某个 session，但想在它内部重定位锚点，用：
32
+
`-a` 取值依赖目标 agent runtime,**装错 slot 会看不到 skill**。装完通常需要重启 agent / 开新 session。
115
33
116
-
```bash
117
-
"${CXS_BIN:-cxs}" read-range <sessionUuid> --query "IME" --before 4 --after 8 --json
118
-
```
34
+
## 什么时候用 cxs
119
35
120
-
5. 只有在 `read-range` 仍不够时，才升级到整页浏览：
36
+
| 场景 | 起手 | 原因 |
37
+
| --- | --- | --- |
38
+
| 用户问"之前 / 上次 / 我记得 / 我们讨论过" | `cxs find` | 先拿 `sessionUuid + matchSeq` |
39
+
| 用户问"本项目最近的对话",且不确定是否 sync 过 | `cxs current` | 直读 Codex state DB,零索引依赖 |
40
+
| 用户给项目名 / cwd / 时间窗,且 cxs 已 sync | `cxs list --cwd ... --since ...` | cwd/since 缩范围比全文搜更稳 |
41
+
| 已锁定某 session,需要局部上下文 | `cxs read-range --seq` 或 `--query` | 局部扩窗,不冷启 `read-page` |
121
42
122
-
```bash
123
-
"${CXS_BIN:-cxs}" read-page <sessionUuid> --offset 0 --limit 40 --json
124
-
```
125
-
126
-
工作流心法：
43
+
**反例**(应该用别的工具):
127
44
128
-
- 永远先 `find`，不要直接 `read-page`
129
-
- `matchSource=session` 表示命中来自 title / summary / compact / reasoning summary 等 session-level 字段，且 `matchSeq=null`；这种结果先 `read-page`，不要伪造 `read-range --seq`
130
-
- 升级到 `read-page` 之前，先尝试放大 `--before/--after`
131
-
- 用户给出 `cwd` 或时间窗口时，优先 `list` 缩范围再 `read-range --query`
132
-
- `cwd` 只是候选过滤，不是主题真相；还要再看 `title`、`summaryText`、开头几条 message
133
-
- 同主题可能返回多个不同 `sessionUuid`；按 `cwd`、`startedAt`、`matchCount` 选，不要按 title 脑补去重
45
+
- 当前 repo 代码/字符串搜索 → 代码搜索工具
46
+
- 当前文件或已知路径阅读 → 文件读取工具
47
+
- 外部文档/网页 → WebFetch / WebSearch
48
+
- 今日提交/日报 → `commit-daily-summary`
49
+
- 当前会话收尾 → `session-wrap`
134
50
135
-
## JSON 模式速查
51
+
## 工作流心法
136
52
137
-
- `find --json`：顶层是 `{ query, results }`；重点看 `sessionUuid`、`matchSource`、`matchSeq`、`summaryText`、`snippet`
138
-
- `read-range --json`：重点看 `anchorSeq`、`rangeStartSeq`、`rangeEndSeq`、`messages[]`
139
-
- `read-page --json`：重点看 `offset`、`limit`、`totalCount`、`hasMore`
140
-
- `list --json`：重点看 `results[].cwd`、`startedAt`、`endedAt`、`messageCount`
141
-
- `stats --json`：重点看 `lastSyncAt`、`dbPath`、`indexVersion`
142
-
- `sync --json`：重点看 `errors`、`errorDetails[]`
143
-
- 完整字段见：`references/json-schema.md`
53
+
- **find → read-range → read-page**:永远先 `find` 拿候选,不要冷启 `read-page`
54
+
- `matchSource = "session"` 时 `matchSeq = null`;这种命中先 `read-page` 抽样,**不要伪造 `read-range --seq`**
55
+
- 用户给 cwd 但不确定 sync 状态 → `current`(零索引依赖);cxs 已 sync → `list`(全索引)
56
+
- `cwd` 只是候选过滤,不是主题真相;还要再看 `title`、`summaryText`、开头几条 message
57
+
- 同主题可能多个 uuid;按 `cwd / startedAt / matchCount` 选,不要按 title 脑补去重
144
58
145
-
## 常用排障
59
+
## 前置
146
60
147
-
| 症状 | 先跑什么 | 怎么处理 |
148
-
| --- | --- | --- |
149
-
| `find` 零结果但用户坚持存在 | `stats --json` | 先看 `lastSyncAt`，必要时 `sync` |
150
-
| `sync` 非零退出 | `sync --json 2>&1` | 看 `errorDetails[]` |
151
-
| `stats/list/find` 报 `database is locked` | 同命令先重试一次 | 还是忙就先跳过 `stats` 直接读 |
152
-
| 同主题出现多条 uuid | `find -n 10 --json` | 按 `cwd`、`startedAt`、`matchCount` 选 |
153
-
| 用户问“最近本项目讨论了什么” | `list --cwd <current-repo> --sort ended --json` | `cwd` 只先圈候选，再抽样确认主题 |
154
-
| 中文关键词搜不到 | 换至少两字中文或英文关键词 | 详见 `references/failure-cookbook.md#cjk-zero-results` |
155
-
| 用户说“在 X 项目里” | `list --cwd X --json` | 先按 cwd 缩范围 |
156
-
| 从别的 cwd 调用找不到 db | `stats --json` | 看 `dbPath` 或显式传 `--db` |
61
+
- 先 `stats --json` 看 `dbPath / lastSyncAt / sessionCount`
62
+
- 索引不存在或 `lastSyncAt` 很旧 → `sync`(默认严格模式;只有用户接受部分成功才加 `--best-effort`)
63
+
- `current` 不依赖 cxs 索引,即使 sync 没跑过也能用
64
+
- 从别的 cwd 调用时,若默认 db 不对,显式传 `--db`
157
65
158
66
## 参考
159
67
160
-
- `references/cli-surface.md`
161
-
- `references/json-schema.md`
162
-
- `references/progressive-workflow.md`
163
-
- `references/advanced-queries.md`
164
-
- `references/failure-cookbook.md`
68
+
详细命令面、字段、流程、错误处理:
69
+
70
+
- [`references/cli-surface.md`](references/cli-surface.md) — 每个子命令的 options + Example
71
+
- [`references/progressive-workflow.md`](references/progressive-workflow.md) — 4 个 worked scenarios
72
+
- [`references/json-schema.md`](references/json-schema.md) — 完整 JSON 字段
73
+
- [`references/failure-cookbook.md`](references/failure-cookbook.md) — 错误症状速查 / state_db_unavailable 处理 / `--json` error shape 速查
74
+
- [`references/advanced-queries.md`](references/advanced-queries.md) — query 语义 / CJK 行为 / snippet 高亮
165
75
166
-
# skill-sync: repo-shared cxs skill, PATH-or-CXS_BIN mode, 2026-04-22
76
+
# skill-sync: repo-shared cxs skill, PATH-or-CXS_BIN mode, 2026-04-27
+28
.agents/skills/cxs/references/cli-surface.md
+28
.agents/skills/cxs/references/cli-surface.md
···
12
12
export CXS_BIN=/absolute/path/to/bin/cxs
13
13
```
14
14
15
+
## current
16
+
17
+
Purpose: 直读 Codex state SQLite,按 cwd 拿候选 session,**不依赖 cxs 自己的索引**(适合 sync 没跑过或刚换机器的场景)。
18
+
19
+
Notes:
20
+
21
+
- 默认 state DB 路径 `~/.codex/state.sqlite`,可用 `--state-db` 覆盖
22
+
- `--cwd` 缺省走 `process.cwd()`,直接拿当前 repo 候选
23
+
- 顶层 `{ cwd, candidates: CurrentSessionCandidate[] }`;每个 candidate 含 `sessionUuid / title / cwd / filePath / updatedAtMs`
24
+
- state DB 不存在/缺 `threads` 表/缺必需列时,`--json` 输出结构化 `{ error: { code: "state_db_unavailable", message } }`,exit code 1
25
+
- 拿到 `sessionUuid` 后通常直接 `read-page` 抽样确认,不需要再走 `find`
26
+
27
+
Options:
28
+
29
+
| option | 说明 |
30
+
| --- | --- |
31
+
| `--cwd <path>` | 指定 cwd,默认 `process.cwd()` |
32
+
| `-n, --limit <n>` | 候选条数上限,默认 100 |
33
+
| `--state-db <path>` | 覆盖默认 Codex state SQLite 路径 |
34
+
| `--json` | 输出 JSON |
35
+
36
+
Example:
37
+
38
+
```bash
39
+
"${CXS_BIN:-cxs}" current --json
40
+
"${CXS_BIN:-cxs}" current --cwd /Users/me/work/foo --json
41
+
```
42
+
15
43
## sync
16
44
17
45
Purpose: 扫描本地 `~/.codex/sessions` 并同步到 SQLite 索引。
+32
.agents/skills/cxs/references/failure-cookbook.md
+32
.agents/skills/cxs/references/failure-cookbook.md
···
12
12
| 用户问“最近本项目讨论了什么” | `list --cwd <current-repo> --sort ended --json` | `cwd` 先圈候选，再抽样读头尾确认主题 |
13
13
| 用户说“在 X 项目里” | `list --cwd X --json` | 先按 cwd 缩范围，再在候选里 `read-range --query` |
14
14
| 从其他 cwd 调用找不到 db | `stats --json` | 看 `dbPath`；必要时显式传 `--db` |
15
+
| `current --json` 输出 `state_db_unavailable` | 看 message | Codex state DB 问题,不是 cxs 本身坏;**不要重跑 sync** |
15
16
16
17
## Find zero results but user insists it exists
17
18
···
56
57
- `summaryText`
57
58
- `read-page` 开头 6 到 8 条
58
59
- `read-page` 结尾 6 到 8 条
60
+
61
+
## state_db_unavailable
62
+
63
+
`cxs current` 直读 Codex state SQLite,跟 cxs 自身索引无关。`--json` 模式下,所有 state DB 不可用都被收口成:
64
+
65
+
```json
66
+
{ "error": { "code": "state_db_unavailable", "message": "..." } }
67
+
```
68
+
69
+
`message` 三类:
70
+
71
+
| message 关键词 | 真实原因 | 处理 |
72
+
| --- | --- | --- |
73
+
| `state db not found: <path>` | Codex state DB 文件不存在 | 用户没装 codex 或 `--state-db` 路径错 |
74
+
| `missing 'threads' table` | DB 存在但缺核心表 | Codex 版本异常或库被截断 |
75
+
| `missing column(s) ...` | `threads` 表缺必需列(`id` / `rollout_path` / `cwd` / `title` / `updated_at_ms`) | 上游 Codex 改了 schema,cxs 需要适配新版 |
76
+
77
+
**关键**:这是 **Codex 端**的问题,**不要尝试 `cxs sync` 修复**——`sync` 写的是 cxs 自己的索引,跟 state DB 毫无关系。直接告知用户检查 codex 安装/版本即可。
78
+
79
+
## --json error shape 速查
80
+
81
+
不同子命令在 `--json` 下的 error 形状不一致,解析时按命令分流:
82
+
83
+
| 命令 | error 出口 | 形状 |
84
+
| --- | --- | --- |
85
+
| `sync`(per-file 错) | stderr | `SyncSummary`,看 `errors / errorDetails[]` |
86
+
| `sync`(锁超时 `SyncLockTimeoutError`) | stderr | `{ "error": <message string> }` |
87
+
| `current`(state DB 问题) | stdout | `{ "error": { "code": "state_db_unavailable", "message": "..." } }` |
88
+
| `find / read-range / read-page / list / stats` 异常 | 进程异常退出 | 当前未结构化,直接非零退出 |
89
+
90
+
**实务**:解析前先看 exit code;非零再判断是结构化(`current`)还是字符串(`sync` 锁超时)还是 summary(`sync` per-file)。
59
91
60
92
## Schema drift
61
93
+24
-1
.agents/skills/cxs/references/progressive-workflow.md
+24
-1
.agents/skills/cxs/references/progressive-workflow.md
···
9
9
硬规则：
10
10
11
11
- 没有 `sessionUuid` 时，不要冷启动 `read-page`
12
-
- 用户给了 `cwd` 或时间窗口时，先 `list`
12
+
- 用户给了 `cwd` 但**不知道是否 sync 过**:先 `current --cwd ...`(直读 state DB,零索引依赖)
13
+
- 用户给了 `cwd` 或时间窗口且 cxs 已 sync,优先 `list`
13
14
- 已锁定 session 但锚点不对时，用 `read-range --query`
14
15
- `cwd` 只是候选过滤，不是主题真相；还要再看 `title`、`summaryText` 和开头几条 message
15
16
···
65
66
- `summaryText`
66
67
- 开头几条 message
67
68
- 结尾几条 message
69
+
70
+
## Worked Scenario 4
71
+
72
+
用户说：`本项目最近的对话` 或 `刚换的机器还没来得及跑 sync`,但你需要立刻拿到当前 repo 的候选 session。
73
+
74
+
先 `current` 直读 Codex state DB(不需要 cxs 自己的索引):
75
+
76
+
```bash
77
+
"${CXS_BIN:-cxs}" current --json
78
+
```
79
+
80
+
输出顶层是 `{ cwd, candidates: [...] }`,每个 candidate 已经按 `updatedAtMs` 倒序。拿最近一条的 `sessionUuid` 直接抽样:
81
+
82
+
```bash
83
+
"${CXS_BIN:-cxs}" read-page <sessionUuid> --offset 0 --limit 20 --json
84
+
```
85
+
86
+
**何时选 current 而不是 list**:
87
+
88
+
- `cxs sync` 没跑过或久没 sync(`stats.lastSyncAt` 很旧/为 null)时,`list` 会拿到陈旧或空结果;`current` 直读 state DB,反映的是 Codex 当前的 thread 列表
89
+
- 只想要"当前 cwd 下最新的 session",不需要全文检索
90
+
- state DB 不存在/缺 `threads` 表/缺必需列时,`current --json` 会返回结构化 `{ error: { code: "state_db_unavailable", message } }`,**不要重跑 sync 试图修复**——那是 Codex 端的问题,提示用户检查 codex 安装即可
68
91
69
92
## 来源
70
93