把想做的事写进看板，让 Codex 自己整理、领取和推进；遇到需要你拍板的地方，再回来找你。
这是一个正在开发的 macOS 本地预览版，不是 OpenAI 官方项目。目前更适合愿意自己运行开发命令的人，还没有面向普通用户的一键安装包。
同时用 Codex 推进多个项目后，左侧栏很容易堆满任务窗口。你很难判断哪些还在做、哪些已经卡住，也得不停打开窗口查看进度。
这个项目把工作管理从原生任务列表里单独拿出来，做成一张真正能调度 Codex 的看板。
你只要写一句自然语言，例如：
给我的个人网站补一个博客，并整理现有文章。
看板会尝试理解这件事属于哪个项目、应该在哪个工作目录里完成，以及执行前还有哪些信息需要确认。你把卡片拖到「待执行」后，后台 Worker（常驻执行进程）才会领取任务。Codex 接到任务后会自动把卡片移到「进行中」。
如果需要你确认技术方案、补充资料或处理阻塞，左侧「工作看板」入口会出现蓝点，macOS 也会发出本机通知。你不用一直盯着看板。
| 你做什么 | 看板做什么 |
|---|---|
| 点击「+」，写下想做的事 | 保存原始文字，不要求你填写 JSON 或目录路径 |
| 查看自动分类结果 | 告诉你分到了哪个项目、依据是什么、还有哪些候选项 |
| 把卡片拖到「待执行」 | 记录你的授权，后台开始规划并领取任务 |
| 等待或处理提示 | Codex 在独立工作区推进；卡住时通过蓝点和本机通知找你 |
| 验收结果 | 卡片依次进入「待验收」「待合并」「完成」，不会自动推送或发布 |
看板分为四个页面：
- 「看板」管理点子和工作阶段。
- 「Project」查看一个长期项目的目标、里程碑、风险和正在推进的工作。
- 「工作区」查看代码目录，以及为什么某张卡片被分到这里。
- 「运行」查看每次 Codex 执行的状态、检查点、结果和错误。
普通看板只记录状态。这个看板还负责把任务交给 Codex。
- 卡片原文始终保留。模型生成的分类和执行计划另存，不会覆盖你写的话。
- 多个项目可以同时推进，没有人为设置的全局并发上限。只有两个任务要同时修改同一份独占资源时，系统才会阻止冲突。
- 每次执行都使用独立的 Git Worktree（Git 隔离工作目录）和临时 Codex 任务。临时任务不会继续堆进原生左侧栏。
- 如果找不到合适的代码目录，看板可以先提出新建独立 Workspace（工作区）的方案。只有你授权后，它才会创建目录并初始化 Git。
- 技术栈、数据库、部署平台等承重选择没有写清楚时，系统会先让你确认，不会替你静默做决定。
下面这些情况会被视为「需要你处理」：
- Codex 正在等你回复。
- 技术选型、项目分类或工作区需要确认。
- 任务被阻断、执行失败或运行状态丢失。
- 结果等待验收，或代码等待你手动合并。
左侧入口的蓝点会一直保留，直到没有待处理项。新问题第一次出现时会发送一条 macOS 通知并播放系统提示音；同一个问题不会因为后台轮询而反复弹窗。通知只显示安全的卡片标题和状态，不会放入完整需求、文件路径或命令输出。
这个项目会读取本机信息，也会在你授权后修改代码。开始使用前，应该知道这些边界：
- Workspace 扫描是只读的，默认从当前用户目录开始，并受目录数量、深度和超时限制。
- 卡片进入「待执行」代表你授权这项工作。自动修改只允许发生在已经验证的 Git Workspace 内，并使用隔离 Worktree。
- 本项目不会自动 merge、push、创建 PR、部署、发布、删分支或改写 Git 历史。
- Desktop Bridge（桌面桥）只连接本机回环地址上的 Codex 调试端口，不开放自己的 HTTP 服务，也不修改 Codex 应用包。
- 工作数据保存在
~/.codex/workboard/workboard.sqlite。数据库、日志和本机运行记录不会提交到这个仓库。 - 模型提出的路径只是建议。确定性代码会再次校验目录、Git 状态、授权和资源冲突。
已经可以使用的部分：
- 自然语言卡片、拖动授权和六阶段看板。
- Project、Workspace、运行中心和可解释分类。
- 找不到合适目录时创建托管 Workspace，并初始化可验证 Git。
- 持久后台 Worker、多任务并行、Git Worktree 隔离和 Codex App Server 执行。
- 暂停、继续、取消、重试、等待用户回复、检查点和结果验收。
- Codex 左侧栏入口、卡点蓝点、macOS 通知和提示音。
- 完成 15 天后的卡片只从默认看板隐藏，数据不会被归档或删除。
仍未完成的部分：
- 一张同时包含多个独立项目的卡片，还不能自动拆成多个可分别授权的工作项。
- 已创建 Project 的目标发生结构性变化时，还没有带前后差异的方向变更提案。
- 运行中心有结构化事件和结果，但还没有完整、可折叠的原始命令输出流。
- 还没有一键安装包，也没有针对非 macOS 平台的后台服务安装器。
如果只想看看界面，不安装后台服务：
git clone https://github.com/hebi-Chinese/codex-working-board.git
cd codex-working-board
npm ci
npm run preview:ui终端会打印本地预览地址。预览使用演示数据，不会扫描目录或启动 Codex 任务。
如果想参与开发，先运行完整检查：
npm run verify
npm audit --audit-level=high项目要求 Node.js 24 或更高版本。npm run verify 会运行测试、TypeScript 类型检查、全部构建、MCP 握手探针和插件清单校验。
完整安装目前只针对 macOS，并假设 Codex Desktop 已安装。
先让 Codex 暴露本机调试端口。应用名称如果不是 Codex，请按你的实际应用名调整：
open -na "Codex" --args --remote-debugging-port=9341然后在仓库目录安装后台 Worker 和左侧栏入口：
npm ci
npm run verify
npm run install:worker
npm run install:desktop-entry
npm run status:worker
npm run status:desktop-entry这两项通过用户级 macOS LaunchAgent 运行。关闭看板或关闭 Codex 窗口，不会撤销已经写入数据库的任务授权。
Codex 插件界面还需要把本仓库登记到一个本地 Plugin Marketplace，再执行 codex plugin add。当前仓库尚未打包成可直接添加的 Marketplace；具体格式见 OpenAI Plugins 文档。
卸载后台服务和左侧栏入口：
npm run remove:desktop-entry
npm run remove:worker卸载服务不会删除 ~/.codex/workboard/ 里的数据库。
项目使用 TypeScript、React、MCP Apps、Node.js SQLite 和 Codex App Server。
src/ui/ 看板、Project、Workspace 和运行中心界面
src/workboard/ 卡片、分类、授权、项目和数据库规则
src/runtime/ 后台 Worker、模型解释和 Codex 运行时
src/execution/ Git 检查、Worktree 和托管 Workspace
src/desktop/ 左侧栏入口、蓝点、本机通知和 CDP 桥
src/mcp/ Codex 插件工具与 UI 资源入口
src/contracts/ UI、后台和领域层共同使用的类型契约
高层设计在 docs/architecture/，项目术语在 CONTEXT.md。开发约束和验证命令在 AGENTS.md。
- 当前版本：
0.5.0。 - 当前主要平台：macOS。
- Desktop 左侧栏入口使用经过校验的本机 CDP/DOM 适配，因为 Codex 目前没有公开的原生侧边栏扩展接口。Codex 更新 DOM 后，这个入口可能暂时失效；MCP Apps 界面和本地数据不依赖这层适配。
- 这是早期项目，数据库迁移目前只保证项目内定义的一次性升级路径。
这个仓库目前没有附加开源许可证。代码可以在 GitHub 上阅读，但不代表已经授予复制、修改或再发布的许可。许可证会在项目所有者明确选择后单独添加。