codex-sprite

A desktop pet shell for VSCode + Codex.

codex-sprite 把多个 VSCode 窗口里的 Codex 状态压成一个桌面层视图。

它适合这种工作方式：

• 同时跑多个 Codex 窗口
• 不想一直盯着聊天面板和终端
• 只想在需要确认、任务完成或出错时被提醒

它做三件事：

• 按 VSCode 窗口聚合状态，不被 subagent 线程刷屏
• 用 thinking / needs-attention / done / error 这些可读状态驱动桌宠动作
• 允许你用一张参考图直接生成新的桌宠形象

动图示例

Thinking 后台仍在推进，但还不需要你回来处理。	Needs Attention 适合表示等待确认、输入或审批。
Done 给一个完成反馈，然后自然回落。	Idle 没有新的活跃事件时，桌宠保持安静。

本地样本

下面这组案例来自真实本地观测，但窗口名已经打码成通用类型。

窗口类型	观测状态	说明
Research Workspace	thinking	适合规划、写作、交互式任务
Toolchain Workspace	thinking	适合长期后台执行的工程任务
Quiet Workspace	idle	适合展示完成或暂停后的自然回落

完整说明见 本地案例展示。

Quick Start

在仓库根目录执行：

npm install
npm run create:pet -- --image ./reference.png

这条命令会自动完成：

1. 检查 codex CLI 和登录状态
2. 分析参考图是否适合单角色桌宠
3. 生成桌宠动作 PNG 帧
4. 校验并替换 assets/pet-direct
5. 重新生成 manifest
6. 安装 companion
7. 启动桌宠

如果 VSCode 已经打开，再执行一次 Developer: Reload Window，让扩展宿主加载最新 companion。

参考图怎么选

更稳的参考图通常满足这些条件：

• 一个主角色
• 发型、服装、轮廓和主色调明显
• 主体没有被严重遮挡
• 半身或全身都能看清

容易失败的情况通常是：

• 多人合照
• 主体只剩局部
• 背景比人物更抢眼
• 角色特征太弱，难以提炼成稳定的 Q 版形象

默认会生成什么

默认模式只生成当前 live 状态真正会用到的 7 组动作：

• idle
• idle-snooze
• thinking
• writing
• peek
• done
• error

对应状态语义：

• idle -> 待机
• idle-snooze -> 长时间空闲
• thinking -> 活跃思考
• writing -> busy
• peek -> needs-attention
• done -> 完成
• error -> 错误

如果你想保留完整扩展素材包，可以使用：

npm run create:pet -- --image ./reference.png --full-pack

常用命令

• 重新生成一套 live 角色动作：npm run create:pet -- --image ./reference.png
• 生成完整 13 动作包：npm run create:pet -- --image ./reference.png --full-pack
• 启动桌宠：npm start
• 重建动作清单：npm run generate:pet-frames
• 重新安装 companion：npm run install:companion
• 语法检查：npm run check

文档

• 从参考图开始
• 高级定制
• 本地案例展示
• 小红书首发素材
• 常见问题

项目结构

• src/main: Electron 主进程、状态聚合、fallback 日志观察
• src/renderer: 桌宠 UI、气泡布局、状态展示和动作映射
• src/shared: companion 和主进程共享的状态协议与归一化逻辑
• companion-vscode: VSCode companion 扩展源码
• assets/pet-direct: 桌宠动作帧
• scripts: 一键生成、manifest 生成和 companion 安装脚本
• prompts: Codex 参考图生成模板和预检 schema

边界

• 面向本地 Linux + VSCode + Codex 工作流
• 一键生成路径依赖 codex CLI
• 重点解决“多窗口状态可见”和“需要你注意时的提醒”
• 不接管聊天流，不做跨平台打包发行