使用 Codex 处理较长任务时，我经常遇到一个很实际的问题：任务放在后台运行后，我很难一眼看出它是在继续工作，还是已经停在某个批准请求上。

于是，我做了 CodexPetMonitor。

它是一只常驻桌面的透明悬浮宠物，也是一块更直观的 Codex 状态面板。Codex 正在执行任务、等待用户批准或者遇到异常时，宠物会用不同的姿态和动作反馈状态。你不必频繁切回 Codex 窗口，只要看一眼桌面，就知道任务进行到了哪一步。

项目已经开源，并同时支持 macOS 和 Windows：

GitHub：landuochong/CodexPetMonitor

它解决了什么问题？

当多个 Codex 任务并行运行时，最容易被忽略的并不是任务完成，而是“任务正在等你”。

比如 Codex 准备执行一个需要授权的操作，批准窗口可能被其他应用遮住。此时任务实际上已经暂停，但如果用户没有及时发现，几分钟甚至更久都会白白浪费。

CodexPetMonitor 把这些状态直接映射成桌面动作：

Codex 状态	宠物表现
空闲	安静待机
正在执行	切换到静止的工作姿态
等待批准或用户输入	持续奔跑，直到请求被处理
任务异常	平滑循环播放哭泣动作
鼠标悬停	一跳一跳地与你互动
鼠标点击	完成一次跳跃

这里最重要的设计是：只有真正需要注意时，宠物才持续运动。

平时它安静待在桌面角落，不会一直扭动分散注意力；一旦有任务等待批准，它就会持续奔跑，直到批准完成或请求结束。相比一次性的系统通知，这种反馈更明显，也不容易错过。

不只是动作，还有任务统计

宠物右下角带有两个小徽章：

• 绿色数字表示正在执行的任务数；

• 红色数字表示等待批准或等待输入的任务数。

当多个任务并行运行时，不用逐个打开窗口检查，当前负载和待处理事项一目了然。任意任务进入等待状态，都会获得最高显示优先级。

徽章不会拦截鼠标操作，宠物依然可以直接拖动到桌面上的任意位置。

像桌面宠物，而不是另一个监控窗口

我不希望它看起来像一块生硬的系统仪表盘，因此在交互和动画上做了不少调整：

• 窗口完全透明、无边框并保持置顶；

• 支持自由拖拽，并可显示在所有桌面空间；

• 鼠标移入时连续跳跃，落地后会自然停顿；

• 奔跑动作连续对称，不会在循环末尾突然卡住；

• 哭泣动作经过缓动处理，避免机械式左右摇晃；

• 空闲和工作时保持静止，只在需要用户关注时持续播放动作。

菜单栏中的爪印图标还提供了自动检测、手动状态预览和退出功能。开发或调试自定义动画时，可以直接切换四种状态查看效果。

它如何感知 Codex 状态？

CodexPetMonitor 完全在本机运行，采用“实时状态优先、本地事件兜底”的双层机制。

首先，它会读取 Codex 的本地任务列表，并连接 Codex Desktop 的本机 IPC 通道。任务状态发生变化时，应用可以立即得到更新。waitingOnApproval 或 waitingOnUserInput 等标记，会直接触发等待处理动作。

如果 Codex 没有运行、IPC 暂时断开，或者新版客户端尚未返回实时快照，应用会自动回退到本地数据库和任务事件文件继续判断。连接成功和状态可用是两个独立条件，因此不会再发生“socket 已经连上，但统计数字被错误清零”的情况。

整个过程只读取本地状态，不会上传提示词、回复内容或任务文件，也不需要辅助功能权限。

说明：Codex Desktop 的本机 IPC 和状态数据库目前不是稳定的公共接口，未来 Codex 更新后仍可能需要进行兼容适配。

macOS 安装

环境要求：macOS 13 或更高版本、Swift 6 和 Xcode Command Line Tools。

git clone git@github.com:landuochong/CodexPetMonitor.git
cd CodexPetMonitor
./scripts/build_macos.sh
open dist/CodexPetMonitor.app

如果希望安装到当前用户的 Applications 目录：

mkdir -p "$HOME/Applications"
ditto dist/CodexPetMonitor.app "$HOME/Applications/CodexPetMonitor.app"
open "$HOME/Applications/CodexPetMonitor.app"

Windows 安装

Windows 版本使用 .NET 8 和 WPF 实现，支持 Windows 10 1809 及以上版本，并提供 x64 与 ARM64 构建方式。

在 PowerShell 中运行：

.\windows\build.ps1 -Runtime win-x64
.\windows\install.ps1 -Runtime win-x64

Windows on ARM 使用：

.\windows\build.ps1 -Runtime win-arm64
.\windows\install.ps1 -Runtime win-arm64

构建产物是自包含程序，最终使用者不需要额外安装 .NET Runtime；安装过程只写入当前用户目录，不需要管理员权限。

支持自定义宠物

当前版本使用一套透明背景的 v2 动画图集。图集包含待机、移动、互动、失败等标准动作，以及多个观察方向。

只要保持相同的图集尺寸、单元格规格和动作行语义，就可以替换成自己的角色，把它做成真正属于自己的 Codex 桌面伙伴。

当前图集规格如下：

• 整体尺寸：1536 × 2288；

• 单元格尺寸：192 × 208；

• 每行 8 帧，共 11 行；

• 第 0–8 行是标准动作，第 9–10 行是 16 个观察方向。

从一个提醒工具，到有生命感的开发伙伴

CodexPetMonitor 最初只是为了提醒我“有任务正在等待批准”，但在不断调整动作节奏、透明窗口、拖拽手感和状态优先级之后，它逐渐变成了桌面上的一个小伙伴。

它不会替代 Codex 自己的任务界面，也不试图展示复杂日志。它只负责一件事：用最直观的方式告诉你，Codex 此刻是否需要关注。

如果你也经常让 Codex 在后台处理任务，欢迎试用、提交 Issue，或者换上自己喜欢的角色素材。

项目地址：github.com/landuochong/CodexPetMonitor

如果这个小工具对你有帮助，也欢迎点一个 Star。