codex-sess

一个用于浏览和恢复 Codex 会话的命令行工具，基于 fzf 提供交互式选择界面。

功能特性

• 📋 交互式会话选择器（基于 fzf）
• 🗂️ 按工作空间分组显示会话
• 🔍 支持搜索和过滤会话
• 📍 显示会话预览（系统时间、来源、工作目录、最近 3 条用户 query）
• ⚡ 一键切换到原工作目录并恢复会话
• 🔧 支持自定义恢复命令别名

安装

# 克隆仓库后，运行安装脚本
./scripts/install-local.sh

安装脚本会在 ~/.local/bin/codex-sess 创建符号链接，使命令在系统范围内可用。

依赖

• Node.js - 运行主程序
• fzf - 交互式选择器
• codex - Codex CLI（用于恢复会话）

使用方法

基本用法

# 启动交互式会话选择器
codex-sess

# 使用初始查询
codex-sess --query "codex-sess"

# 自动选择匹配的会话（无需 fzf）
codex-sess --filter "codex-sess"

# 使用自定义命令别名
codex-sess --alias "codexd"

命令选项

| 选项 | 说明 | |------|------| | --query TEXT | 传递初始查询给 fzf | | --filter TEXT | 自动选择唯一匹配的会话（不启动 fzf） | | --alias CMD | 使用替代命令恢复会话（默认：codex） | | --print-selection | 输出选中的会话 JSON | | --dry-run | 打印恢复命令但不执行 | | --help, -h | 显示帮助信息 |

环境变量

| 变量 | 说明 | 默认值 | |------|------|--------| | CODEX_SESS_BASE_DIR | 项目基础目录（用于分组） | /mnt/d/projects | | HOME / USERPROFILE | 会话存储根目录 | - |

工作原理

1. 扫描 ~/.codex/sessions/**/*.jsonl 目录
2. 解析每个 JSONL 文件，提取会话元数据和最近 3 条用户 query（用于 preview）
3. 按时间戳降序排序（最新的在前）
4. 按工作空间路径分组显示
5. 选择后切换到原工作目录并执行 codex resume <session_id>

列表中的时间来源为“最后一次 chat 消息时间”（response_item 且 payload.type=message），并按系统本地时区显示；若没有 chat 消息则回退到 session_meta.timestamp。

会话显示格式

列表视图

===== js/codex-sess =====
03-11 11:56 · 实现 codex-sess
03-11 10:20 · add retry logic

===== [outside /mnt/d/projects] =====
03-10 15:30 · fix login bug

预览面板

ID: 019cdb0a-2d98-7922-9338-7ac20df10faf
Time: 2026-03-11T03:56:43.307Z
Source: cli
Workspace: /mnt/d/projects/js/codex-sess

Recent user queries (last 3):
1. 实现 codex-sess
2. 加个 alias 参数
3. 按项目分组展示

Command:
cd /mnt/d/projects/js/codex-sess && codex resume 019cdb0a-2d98-7922-9338-7ac20df10faf

开发

运行测试

# 运行所有测试
npm test

# 运行单个测试
node --test --test-name-pattern="testNamePattern" tests/

直接执行

node src/codex-sess.js [options]

许可

MIT