Codux：一个开源的多项目 AI 终端，Codex、Claude Code 按项目统一管理——聊聊设计思路

先交代背景：我从 2024 年开始用 AI 写代码，这两年多下来，日常开发基本就是给 agent 派活，Codex 跑重构、Claude Code 修 bug，经常几个项目并行。工具本身都很强，但用久了发现真正花时间的不是模型，是模型周围那一圈事。

数了数至少五个：切到别的项目就不知道那边 agent 是在跑还是早停了；两个 agent 改同一个工作区，git 直接乱掉；长任务跑一半人得走；想让 agent 查个测试库，密码怎么给它是个无解题；还有每个新会话都得重新交代一遍项目约定，月底 token 花哪了也没数。

找了一圈没有顺手的，三个月前开始自己写。就是 Codux，GPL-3.0 开源，刚到 2.0 RC。这篇按设计过程讲，每个功能说清楚为什么这么做。

为什么不用 Electron

我要的是常驻桌面、同时渲染好几个高频刷屏终端的东西，Electron 一开始就出局了。最后选了 GPUI——Zed 编辑器背后的 UI 框架：GPU 渲染，多终端同时输出帧率稳；纯 Rust，跟终端仿真层（alacritty 的 crate）、PTY 层、网络层一个语言栈；Entity 加观察者的状态模型，配快照渲染，数据不变就不重绘。

代价也真实：文档少，控件基本自己造，Linux 桌面支持还不成熟（所以 Codux 的 Linux 目前只有无界面主机端）。坑随便举两个：快照构建器里不能反读 view entity，观察者触发时实体还在更新租约里，读了直接 panic；从 action handler 同步可达的观察者，写回 app 状态必须 defer。这些够单独写三篇，有人想看我就展开。

好处是终端能磨得很细：⌘F 搜滚动历史直接跳转、悬浮终端窗口、往终端粘截图自动落盘成文件路径（发图给 AI CLI 就是粘贴回车两步）、IME 候选框严格跟光标、终端标题直接显示在跑的 AI 工具和模型。这些不是功能列表凑数，是自己每天泡十小时攒出来的需求。

状态探测：不写文件、不改配置、不装 hook

Codux 要知道 8 个 CLI（Codex、Claude Code、OpenCode、Kiro CLI、Kimi Code、CodeWhale、MiMo Code、Agy）各自的状态和 token 用量，还要给它们注入上下文。最省事的路是往用户项目写提示词文件、改全局配置、挂 hook——市面上不少工具就这么干的。

我把这三条全划成红线。状态靠进程探测加各家会话文件的增量解析，能分出"生成中 / 等确认 / 闲着 / 结束"——其中"等确认"单独点亮，因为 agent 停在 y/n 上等你四十分钟这种事真的发生过（在我身上）。上下文注入只走官方口子：Codex 的 developer instructions、Claude Code 的--append-system-prompt、OpenCode 的托管 plugin、Kimi 的--agent-file；没有确认的非侵入通道的工具，宁可不注入也不硬写文件。

这条红线成本不低，但用户卸载之后环境干干净净，我觉得值。

worktree 当任务容器

并行 agent 打架的根子是共享工作区，与其在提示词里求它们别乱动，不如物理隔离。Codux 里每个任务就是一个 git worktree，绑自己的终端组、git 状态、文件视图和 AI 会话，切任务是整套原子切换。三天后切回来，终端还停在原地。配套的 git 面板支持目录级 stage / unstage / discard，agent 的改动当场核。

凭证：知道的和使用的不是同一方

全项目我最较真的部分。

威胁模型很直白：密码进了提示词，就进了模型上下文，然后进会话记录，可能进日志，最坏进训练数据。让 agent 读配置文件更糟，等于把~/.ssh整个交出去。

所以把"知道凭证"和"使用凭证"拆开：连接配置在桌面端保存、可测连通；agent 侧只有两个命令，codux-ssh <配置名> -- '<命令>'和codux-db <配置名> -- '<SQL>'。list 只返回配置名和主机名，真实密码和私钥在辅助进程内部注入，模型全程只见过配置名。数据库标只读的配置，wrapper 在语法层做单语句白名单，DROP 和 UPDATE 直接被拒——不依赖提示词自觉。

一句话：安全边界画在进程边界上，不画在提示词里。

人可以走，任务不走

"手机接管"听着像远程桌面，架构上完全不是。桌面、手机（iOS/Android）、无界面主机端互为 peer：传输层是端到端加密的 P2P 直连，NAT 打不通回落中继，中继只见密文，不需要公网 IP；会话层上任务（PTY、agent 进程）永远跑在主机上，操控端接的是同一个活着的会话——手机上回车、确认权限、看实时输出，回到桌面接着用，断线重连恢复的还是这批。

主机端codux-agent一行脚本装（自动识别系统架构，GitHub 慢可以--mirror），codux install注册 launchd/systemd 服务，codux qrcode出码配对，codux update自己升级。家里吃灰的 Mac mini 从此有了工作。

这块最难啃的是远程终端协议：增量帧加基线快照、多观看端各自 ack、尺寸的单一所有权租约（手机和桌面同时看一个 PTY 不能抢 resize）、跨宽度不重排的滚动历史。迭代了四轮才稳，值得以后单独写。

顺手做了个隧道浏览器：桌面连上主机后，内置浏览器以主机身份上网。主机跑着 Vite，本地输127.0.0.1:5173直接开，HMR、WebSocket、.local、VPN 路由都通，不用配端口转发。

记忆和账本

本地记忆分三层——用户偏好、项目画像、模块笔记，开新会话自动注入（走上面的官方通道）。效果就是不用每次都说"这项目用 pnpm、测试跑 just test"。

token 记账按工具/模型/项目/worktree/日期切，30 分钟粒度加按天热力图，本地 SQLite。哪个项目烧钱、自己几点在干活，看图就行。

没有云端，没有账号，所有数据在用户机器上。

以及一只宠物

agent 烧的每个 token 都在喂一只像素宠物，智慧/混沌/夜行/体力/共情五个属性长自真实作息，熬夜党夜行值拉满。支持自定义皮肤和退役名册。没什么用，但每天都想看一眼。

现状

macOS 最稳（14+）；Windows 11 可用、还在磨；Linux 桌面被 GPUI 卡着，目前只有无界面主机端；主机端配对连接是 beta。更新很勤。

brewinstall--caskduxweb/tap/codux# macOS 桌面curl-fsSLhttps://raw.githubusercontent.com/duxweb/codux/main/apps/agent/scripts/install.sh|sh# 主机端

• GitHub：https://github.com/duxweb/codux
• 官网：https://codux.dux.cn
• 手机 App：github.com/duxweb/codux-flutter/releases