CODESK

Terminal workspace for Codex

CODESK 是一个用 Rust + Ratatui 编写的终端工作台，用来在一个终端窗口里组织本机的 Codex 会话、查看工作区文件和浏览 Git 变更。

它不是 codex-rs 的编译版本，也不把 Codex CLI 嵌入 CODESK 二进制。CODESK 运行时优先调用 PATH 中的 codex；通过 npm 安装时，如果 PATH 中没有 Codex，则使用 npm 自动安装的 Codex CLI。中间栏通过 PTY 承载 Codex 原生界面，左右两栏负责会话、项目和文件工作区。

项目特色

• 原生 Codex 体验：中间栏直接承载本机 Codex CLI 的 PTY，保留原生输入、颜色、鼠标协议、审批交互和终端布局。
• 项目与会话集中管理：左侧按工作目录组织 Codex 会话，通过 App Server 读取历史会话、运行状态和额度信息。
• 三栏工作台：同一个终端窗口同时查看会话、项目文件、Git changes、代码预览和 diff，不需要在多个窗口之间来回切换。
• 美观的代码阅读体验：使用 two-face 提供的 syntect 语法定义和 Catppuccin 主题，根据终端深浅背景切换 Mocha / Latte，并按后缀和常见无后缀文件名自动识别代码语言。
• 受限编辑与搜索：支持工作区内的轻量编辑、磁盘变更检测、文件搜索和基于 ripgrep 的全局代码搜索，编辑范围始终限制在当前工作区。
• 语义代码导航：通过语言服务查找代码定义和引用，支持跳转以及前进/后退历史。
• 键盘优先，兼顾鼠标：面板切换、会话恢复、文件浏览、搜索和编辑都有快捷键，同时支持终端和文件区域的鼠标选择、滚动与点击。
• 跨平台 npm 分发：通过 npm 安装预编译二进制，主包会自动选择当前系统对应的 Linux、macOS 或 Windows 平台包。

当前界面

CODESK 把一个 Codex 工作流拆成三个相互配合的区域：

• 左栏：按工作目录分组的 Codex 会话列表，以及 App Server 状态和额度信息。
• 中间栏：Codex 的原生终端界面，包括输入、审批、命令输出和会话历史。
• 右栏：当前项目的文件导航、Git changes、文件预览、彩色 diff 和受限编辑器。
• 底部：当前工作目录、Git 分支和当前焦点面板的快捷键提示。

这种布局适合一边让 Codex 在中间执行任务，一边在左侧切换项目和历史会话、在右侧检查代码和 Git 变更。面板外框始终存在，活动区域会通过标题、边框、行首色标和加粗文字保持清晰的视觉层级，同时沿用终端默认前景色和背景色。

功能列表

Codex PTY

• [x] 启动 codex --no-alt-screen -C <工作目录>，恢复会话时额外传入 --session <SESSION_ID>。
• [x] 保留 Codex 原生键盘、颜色、鼠标协议、审批交互和终端布局。
• [x] 每个打开的会话拥有自己的 PTY 和虚拟终端 scrollback，最多保留 10,000 行历史。
• [x] 新建会话首次打开时显示 CODESK 启动画面；恢复已有会话时直接进入 Codex 内容。
• [x] CODESK 退出时只停止自己创建的 Codex PTY，不主动停止共享的 Codex App Server。

终端宠物

• [x] Linux/X11 使用独立透明浮窗显示宠物，画布右边缘跟随中间 PTY 区域。
• [x] 根据当前输入框显示状态播放入场、睡觉和离开动作；睡眠尾巴按固定帧率摆动。
• [x] 配置开关默认开启；Linux 用户可通过 ~/.config/codesk/config.json 中的 pet.enabled: false 关闭，或使用 $XDG_CONFIG_HOME/codesk/config.json。

项目与会话

• [x] 通过 codex app-server proxy 读取本机 App Server 的会话列表。
• [x] 如果 App Server 尚未运行，会尝试执行 codex app-server daemon start 后重试。
• [x] 会话按工作目录分组，项目按路径排序；同一项目下的会话按 updatedAt 从新到旧排列。
• [x] 项目可折叠。项目收起后，仍会在项目行旁显示最新子会话状态。
• [x] 状态只有三种有意义的显示：运行中的动态 spinner、完成后的 ✓ 和错误的 ×；这两种终态标记都会保留约 3 秒后自动隐藏，无法识别的状态不额外占用状态位。
• [x] 左栏初次加载、刷新、重命名和删除会话都有明确的进行中反馈；双击会话重命名，Delete 异步删除选中的会话。
• [x] Ctrl-N（macOS：Command-N）打开新会话目录对话框，默认填入左栏指针所在项目或会话的工作目录；支持路径编辑和 Tab 补全。
• [x] 左栏当前选中行使用行首色标和加粗文字；当焦点离开左栏时，焦点高亮收起，指针回到当前活动会话，不会产生第二条指针。
• [x] App Server 会话列表默认每 5 秒刷新一次，单次最多读取 100 个未归档会话。AGENT STATUS 显示连接状态、5 小时额度和周额度；如果 App Server 没有返回某项数据，就显示动态加载或 --，不会伪造百分比。

文件、Git changes 与预览

• [x] 右栏从当前工作目录开始导航，不关闭文件树即可在旁边打开文件预览或 diff。
• [x] g 在完整文件树和 Git changes 之间切换；文件名旁显示 Git 状态标记。
• [x] d 查看当前文件的 git diff HEAD；未跟踪文件会生成对应的新文件 diff。
• [x] diff 对新增行、删除行和 hunk 标记使用不同的前景色和粗体提示，不依赖固定行背景色。
• [x] 普通文本预览使用 two-face 提供的 syntect 语法定义和 Catppuccin Mocha / Latte 主题，按终端深浅背景切换主题；按文件后缀及常见无后缀文件名识别多种语言，无法识别时安全退回纯文本。
• [x] 目录导航和代码/ diff 阅读区各自维护独立选区。当前焦点面板按平台对应的复制键只复制自己的选区，不会把两个面板拼接或互相覆盖。
• [x] 右栏打开预览后，文件树保持可见；Esc 先关闭编辑器或预览，再次按下才关闭右栏。
• [x] Ctrl-F（macOS：Command-F）打开代码搜索；Alt-F（macOS：Option-F）打开文件名和路径搜索；结果按目录树展示。
• [x] 搜索面板支持文件搜索和全局代码搜索。代码结果按目录、文件和匹配行分组，打开结果后会定位到目标行并高亮匹配内容。
• [x] 搜索通过后台 ripgrep 任务执行，输入变化会取消旧任务，结果会流式显示且最多保留 500 条，不阻塞中间 PTY。
• [x] 对 Go、Python、JavaScript/TypeScript 和 Vue 文件使用对应的语言服务查找定义与引用；可导航的符号会在预览区标记。
• [x] 在预览区按 Ctrl-D（macOS：Command-D）或 Ctrl/Command-单击跳转；多个目标会显示选择列表，Ctrl/Command-← 和 Ctrl/Command-→ 可在导航历史中前进或后退。
• [x] 如果对应语言服务未安装，CODESK 会显示可复制的安装命令。语言服务由 CODESK 按需启动，导航请求不会阻塞界面。

受限编辑器

• [x] 在普通文件预览中按 e 进入编辑；diff 视图不能直接编辑。
• [x] 支持插入、删除、方向移动、分页、行号、保存和从磁盘重新加载。
• [x] Ctrl-S（macOS：Command-S）保存，Ctrl-Shift-R（macOS：Command-Shift-R）放弃本地修改并从磁盘重载。
• [x] 文件必须位于当前工作区内，禁止编辑符号链接、二进制文件和超过 256 KiB 的文件。
• [x] 保存前会检查磁盘快照；文件被其他进程修改后，CODESK 会拒绝覆盖并要求先重载。

后续功能规划

• [ ] 宠物状态反馈：结合 Codex 会话结果、任务进度和 AGENT STATUS 提供轻量的状态反馈与陪伴体验。

运行要求

• 使用 npm 安装时需要 Node.js >=18；npm 会自动安装 Codex CLI 和 ripgrep 运行时依赖。
• 如果本机已有 codex，CODESK 会优先使用 PATH 中的版本；也可以用 --codex-path 指定可执行文件路径。从源码运行时，Codex CLI 和 rg 需要在 PATH 中可用。
• 当前工作目录最好是 Git 仓库；Git 用于分支、文件状态和 diff，缺少 Git 时这些信息会退化为空状态。
• 系统需要能够提供终端剪贴板能力；终端选择和文件选择复制都使用系统剪贴板。
• 从源码运行或构建时，还需要能够编译 Rust 2024 edition 的 Rust 工具链。

终端显示

• CODESK 主界面沿用终端默认前景色和背景色；主题色按 truecolor、256 色、16 色或无颜色模式降级。嵌入的 Codex PTY 按深浅模式获得兼容的默认色响应。
• 深浅背景优先读取 COLORFGBG；没有该变量时默认按深色终端处理。可通过 CODESK_THEME=light 或 CODESK_THEME=dark 指定背景模式；CODESK_THEME=mono 或 NO_COLOR 可关闭颜色。
• 检测到非 UTF-8 locale 时，边框和图标会回退到 ASCII；也可通过 CODESK_ASCII=1 强制使用 ASCII 符号。

终端宠物

终端宠物默认开启，目前浮窗显示只支持 Linux/X11。Linux 用户可以在 $XDG_CONFIG_HOME/codesk/config.json 中关闭；未设置 XDG_CONFIG_HOME 时使用 ~/.config/codesk/config.json：

{
  "pet": {
    "enabled": false
  }
}

会话完成、出错或等待确认时播放音效，不显示系统通知；音效默认开启并内置在 CODESK 可执行文件中。在配置文件的 pet 对象中设置 "sound_enabled": false 可关闭，或用 "sound_file": "/path/to/sound.wav" 指定自定义音频。自定义 WAV 也可放在配置目录下并命名为 pet-status.wav。

npm 安装

推荐使用 npm 安装预编译版本，不需要本地安装 Rust。主包会根据当前操作系统和 CPU 架构自动选择对应的平台二进制包。

# 安装 CODESK
npm install -g @jiawei666/codesk

# 启动
codesk

# 直接打开指定项目
codesk --cwd /path/to/project

npm 包会自动安装 Codex CLI 和 ripgrep 作为独立依赖，不会将它们打进 CODESK 平台二进制。若本机的 codex 已在 PATH 中，CODESK 会优先使用它；需要指定版本或路径时可使用 --codex-path。

更新 CODESK：

npm update -g @jiawei666/codesk

如果所在网络的 npm 镜像还没有同步最新版本，可以临时指定官方 npm registry：

npm install -g @jiawei666/codesk@latest --registry=https://registry.npmjs.org/

本地运行

在仓库根目录执行：

cargo run --

常用启动参数：

# 指定工作目录
cargo run -- --cwd /path/to/project

# 指定 Codex 可执行文件
cargo run -- --codex-path /path/to/codex

# 启动并恢复已有会话
cargo run -- --cwd /path/to/project --session SESSION_ID

# 查看参数说明
cargo run -- --help

编译 release 二进制：

cargo build --release
./target/release/codesk --cwd /path/to/project

命令行参数只有以下三项：

| 参数 | 说明 | 默认值 | | --- | --- | --- | | --codex-path PATH | Codex CLI 的可执行文件路径 | codex | | --cwd DIR | 初始工作目录 | 当前目录 | | --session SESSION_ID | 要恢复的 Codex 会话 ID | 新建会话 |

快捷键

全局与面板焦点

| 快捷键 | 作用 | | --- | --- | | Tab | 顺时针切换已打开的面板；中间栏正在输入 /... 命令时交给 Codex 补全 | | Shift-Tab | 反向切换面板；中间栏正在输入 /... 命令时交给 Codex | | Ctrl-Tab / Ctrl-Shift-Tab（macOS：Command-Tab / Command-Shift-Tab） | 左右侧栏聚焦时强制切换面板 | | F7 / F8 | 显示/隐藏左右侧栏 | | Ctrl-F（macOS：Command-F） | 打开代码搜索 | | Alt-F（macOS：Option-F） | 打开文件名和路径搜索 | | Ctrl-← / Ctrl-→ | 在文件搜索和代码搜索之间切换 | | Esc | 左栏焦点返回中间栏；右栏按层关闭编辑器、预览和右栏 | | Ctrl-Q（macOS：Command-Q） | 打开退出确认；Enter/y 确认，Esc/n 取消 | | Ctrl-N（macOS：Command-N） | 打开新建会话目录对话框；不会在左栏常驻 New session 行 |

F7 打开或关闭左侧栏，F8 打开或关闭右侧栏。macOS 使用 Command-N/F/Q、Option-F 搜索文件。Command-Tab 通常由 macOS 用来切换应用；如果终端把它转发给 CODESK，侧栏焦点下会切换面板，中间栏则交给 Codex。Linux 使用 Ctrl-Tab 执行侧栏面板切换。

中间 Codex 面板

| 快捷键/操作 | 作用 | | --- | --- | | 普通键盘输入 | 原样发送给 Codex PTY | | Alt-↑/↓（macOS：Option-↑/↓） | 上下滚动 PTY 历史 | | PageUp / PageDown | 按页滚动 PTY 历史 | | Alt-Home/End（macOS：Option-Home/End） | 跳到 PTY 历史顶部/当前屏幕 | | 鼠标左键拖拽 | 选择终端文本；没有选区时点击仍交给 Codex 的鼠标协议 | | 鼠标滚轮 | 优先滚动中间栏自己的终端历史 | | Ctrl-C | 向 Codex 发送终端中断；macOS 上快速连按两次退出 CODESK | | macOS Command-C | 复制选中的终端文本；不触发中断或退出 | | Ctrl-Shift-C | 终端使用该快捷键复制选区时，由 CODESK 接管复制 |

左侧项目与会话栏

| 快捷键/操作 | 作用 | | --- | --- | | ↑ / ↓ | 选择项目或会话 | | Home / End | 跳到列表首尾 | | ← / → | 折叠/展开当前项目；会话行上也会作用于其所属项目 | | Enter | 恢复选中的会话；在项目行打开以该项目目录为默认值的新会话弹窗 | | Delete | 异步删除选中的已有会话 | | r | 从 App Server 刷新会话列表 | | 鼠标滚轮 | 按列表方向移动选择 | | 鼠标左键 | 选择并打开会话；双击会话编辑名称；双击项目折叠/展开 |

右侧文件栏

| 快捷键/操作 | 作用 | | --- | --- | | ↑ / ↓ | 选择文件或目录 | | PageUp / PageDown | 按页移动选择或预览滚动 | | ← / Backspace | 返回父目录；在根目录关闭预览 | | → / Enter | 进入目录或打开文件预览 | | g | 切换完整文件树 / Git changes | | d | 打开当前文件的 diff；预览中切换文件 / diff | | r | 刷新目录或重新读取当前预览 | | e | 在普通文件预览中进入编辑器 | | 预览中的 Esc / Backspace | 关闭当前预览；编辑器用 Esc（无未保存修改时）关闭 | | Ctrl-S（macOS：Command-S） | 保存编辑器内容 | | Ctrl-Shift-R（macOS：Command-Shift-R） | 从磁盘重载并丢弃本地编辑 | | Ctrl-D（macOS：Command-D） | 从代码预览中的光标位置跳转到定义或引用 | | Ctrl/Command-← / Ctrl/Command-→ | 在代码预览的导航历史中后退 / 前进 | | Ctrl-单击（macOS：Command-单击） | 跳转到鼠标指向代码符号的定义或引用 | | 鼠标左键拖拽 | 选择目录文本或代码文本 | | Ctrl-C（macOS：Command-C） | 复制当前右栏选区 |

搜索面板打开时：

| 快捷键/操作 | 作用 | | --- | --- | | Tab / Shift-Tab | 在模式标签、搜索框和结果树之间切换焦点 | | Ctrl-← / Ctrl-→ | 切换文件搜索 / 代码搜索 | | ↑ / ↓ | 选择搜索结果 | | Enter | 文件搜索打开文件；代码搜索打开文件并定位匹配行 | | Esc | 关闭搜索面板并恢复普通文件树 | | 鼠标点击模式标签 | 切换搜索方式 |

项目结构

codesk/
├── src/main.rs                 # 参数解析和程序入口
├── src/app.rs                  # TUI 生命周期、焦点、会话切换
├── src/app_server.rs           # App Server proxy、会话和额度读取
├── src/terminal.rs             # Codex PTY、虚拟终端和终端选区
├── src/search.rs               # 右栏搜索面板和搜索结果树
├── src/search_engine.rs        # 后台 ripgrep 搜索任务和结果解析
├── src/code_navigation.rs      # 语言服务驱动的定义/引用导航与位置选择
├── src/language_service.rs     # 项目语言服务进程与非阻塞请求
├── src/navigation_history.rs   # 代码导航前进/后退历史
├── src/files.rs                # 文件树、Git 状态、预览、diff 和复制
├── src/editor.rs               # 工作区边界内的轻量编辑器
├── src/syntax.rs               # 文件预览语法着色
├── src/ui.rs                   # 三栏布局、状态标记和快捷键提示
├── src/theme.rs                # CODESK 和代码预览颜色
├── bin/codesk.js               # npm 主包的跨平台 launcher
├── scripts/                    # npm 平台包生成和版本检查脚本
├── package.json                # npm 主包元数据
└── .codex/skills/              # 项目级 Codex 工作流 skill

设计边界

• CODESK 不编译或修改 codex-rs。
• CODESK 不接管 Codex 的会话存储；会话元数据通过 App Server 读取。
• App Server 是会话和额度的控制/元数据平面，PTY 是中间栏的交互/渲染平面。
• 右侧文件操作始终受当前工作区边界限制，不提供任意路径编辑能力。
• CODESK 只负责自己创建的 PTY；退出时不杀掉其他 Codex 客户端或共享 daemon。