认识蓝木偶

蓝木偶（Blue Puppet）是一只运行在 Windows 桌面上的 Claude Code 状态宠物。它接收 Claude Code 的 HTTP Hook 事件，把不同会话的工作进度变成看得见的表情、动作和气泡。

程序启动后只显示托盘图标。某个会话的首个已配置事件到达时，蓝木偶会为它创建一个专属宠物；多个会话可以同时存在，互不干扰。

核心能力

能力	说明
多会话多实例	按 session_id 创建并路由宠物，每个实例有独立状态、位置和动画
七种状态	idle、working、question、error、happy、done、sneaky
三款立体形象	蓝木偶、金红战神、钢铁侠，新实例依次分配，也可单独切换
后台任务感知	前台结束时继续检查后台任务，仍在运行就显示“暗中使劲”
会话标题同步	先显示首条提问摘要，随后自动替换为 AI 会话标题
纯代码渲染	tiny-skia 与内置 3D 软光栅管线，不依赖宠物贴图包
本地交互	透明置顶、拖拽、气泡、鼠标跟随、右键菜单和托盘控制

本地架构

Claude Code HTTP Hooks
        │ 完整事件 JSON
        ▼
POST http://127.0.0.1:48291/state
        │
        ▼
蓝木偶内置 HTTP 服务
        │ 按 session_id 路由
        ▼
会话状态机 + 动画 + 鼠标跟随
        │
        ▼
每个会话一只独立桌面宠物

HTTP 服务默认只绑定 127.0.0.1。状态由宠物端根据 hook_event_name 和 tool_name 推断，Hook 不需要额外传递 state 字段。

运行环境

• Windows；当前已在 Windows 11 和高 DPI 缩放下验证。
• Rust 版无需额外运行时，构建后可单文件运行。
• 从源码构建需要 Rust 1.86+ 与 Windows MSVC 工具链。
• Claude Code 需支持 http 类型 Hooks。

Rust 版优先

文档默认介绍当前 Rust 版。仓库中的 Python/PySide6 代码是早期参考实现，不包含 Rust 版的全部新能力。

下一步

• 快速开始
• 查看完整 Hooks 配置
• 了解七种状态与交互