# CxSessionBrowzer

**Repository Path**: mgdh5/cx-session-browser

## Basic Information

- **Project Name**: CxSessionBrowzer
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-19
- **Last Updated**: 2026-05-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Codex 会话浏览器

Codex 会话浏览器是一个本地网页工具，用来检索、预览、筛选并恢复 Codex CLI 保存在 `~/.codex/sessions` 下的会话。

这个工具面向 macOS 本机使用。服务只绑定 `127.0.0.1`，直接从磁盘读取 session JSONL 文件，不上传对话内容，也不会把对话内容写入持久化索引或数据库。

## 首版功能

- 从 `~/.codex/sessions/**/*.jsonl` 读取本机 Codex 会话。
- 按文件更新时间从新到旧排序。
- 使用服务端分页，每页 15 个会话，保证首屏加载快。
- 默认展示最后两段 user/assistant 对话摘要。
- 支持全局展开/收起，并可用滑块选择展开后显示的摘要段数。
- 支持按会话记录的 `cwd` 路径筛选。
- 展示高频 `cwd` 快捷筛选项，并显示对应会话数量。
- 后台构建进程内内存关键词索引。
- 支持按关键词筛选，并可与 `cwd` 路径筛选组合使用。
- 在界面中展示关键词索引状态。
- 点击 `恢复会话` 后打开 macOS Terminal.app，并执行 `codex resume <sessionId>`。

## 环境要求

- macOS
- Node.js 25，或兼容的现代 Node.js 运行时
- Codex CLI 已安装，并可通过 `codex` 命令调用

## 安装

```bash
npm install
```

## 运行

```bash
npm run dev
```

打开 `http://127.0.0.1:58173`。

开发命令会启动两个本地服务：

- 网页界面：`http://127.0.0.1:58173`
- API 服务：`http://127.0.0.1:54174`

可以通过环境变量覆盖 API host 或端口：

```bash
CODEX_SESSION_BROWSER_HOST=127.0.0.1 CODEX_SESSION_BROWSER_PORT=54174 npm run start
```

## 使用方法

1. 打开 `http://127.0.0.1:58173`。
2. 默认按更新时间从新到旧浏览会话。
3. 使用 `上一页` / `下一页` 翻页。
4. 使用 `展开段数` 和 `全部展开` 查看更多对话摘要。
5. 使用路径输入框或快捷筛选项按 `cwd` 路径过滤会话。
6. 使用 `关键词` 输入框按关键词过滤会话。
7. 同时使用 `cwd` 和关键词筛选，可以进一步缩小结果范围。
8. 点击 `恢复会话`，会打开 Terminal.app 并恢复选中的 Codex 会话。

关键词搜索使用后台内存索引。索引构建期间，第一页会话仍然可以正常浏览。索引只存在于当前进程中，服务重启后会重新构建。

## 恢复会话行为

`恢复会话` 按钮会打开 macOS Terminal.app，并执行：

```bash
cd "<session cwd>"
codex resume <sessionId>
```

如果该会话没有记录工作目录，则会直接执行：

```bash
codex resume <sessionId>
```

自动化测试会设置 `CODEX_SESSION_BROWSER_MOCK_RESTORE=1`，因此测试过程中不会打开真实 Terminal。

## API

- `GET /api/health`
- `GET /api/sessions?page=1&pageSize=15`
- `GET /api/sessions?page=1&pageSize=15&cwd=<path-fragment>`
- `GET /api/sessions?page=1&pageSize=15&keyword=<term>`
- `GET /api/sessions?page=1&pageSize=15&cwd=<path-fragment>&keyword=<term>`
- `GET /api/cwd-options`
- `GET /api/search-index`
- `POST /api/sessions/:id/restore`

## 验证

```bash
npm run test
npm run build
npm run test:e2e
openspec validate codex-session-browser
```

## 说明

- 这个工具只面向本机使用，适合在可信任的本地机器上运行。
- 工具不会写入数据库，也不会写入持久化搜索索引。
- 读取 Codex session 文件时会做容错处理，格式异常的文件会被跳过。
- 首版的 Terminal 恢复能力仅支持 macOS。