Pixel Agents — 它是什么

Pixel Agents 是一个工具，可将终端中运行的 AI 编码代理转变为在微型办公室中工作的动画像素艺术角色。您不再看到原始文本滚动，而是看到一个小角色走到办公桌前坐下，编辑文件时打字，搜索时阅读，并在等待您的输入时举起视觉旗帜。

两种运行方式

同一代码库以两种形式提供：

• VS Code 扩展 — 可从 VS Code Marketplace 或 Open VSX 安装。代理启动到 VS Code 终端中；角色出现在终端旁边的面板中。
• 独立 CLI — 在项目文件夹中运行 npx pixel-agents。它会启动一个本地服务器，并在浏览器中显示相同的办公室。适用于 tmux、远程机器和非 VS Code 工作流。

主要功能

• 一个代理，一个角色 — 每个 Claude Code 终端都有自己的动画角色。
• 实时活动跟踪 — 角色根据代理实际执行的操作（写入、读取、运行命令）进行动画。
• 办公室布局编辑器 — 使用内置编辑器设计您的办公室，包括地板、墙壁和家具。
• 对话气泡 — 当代理等待输入或权限时显示视觉指示器。
• 声音通知 — 当代理完成一轮或请求权限时，可选提示音。
• 子代理和团队 — 临时子代理和持久的 Claude 队友作为单独的角色出现，包括团队角色和生命周期变化。
• 持久布局 — 您的办公室设计会保存并在 VS Code 窗口之间共享。
• 共享布局和资源 — 导入/导出布局，并加载外部角色、宠物和家具包。
• 区域 — 在办公室上绘制命名区域，将工作区文件夹映射到这些区域，新代理会坐在映射到其文件夹的区域中。
• 多样角色 — 6 个内置角色（基于 JIK-A-4 的免费角色包，Metro City）。

要求

• 已安装并配置 Claude Code CLI（这是目前唯一支持的 AI 代理；Codex、Gemini、Cursor 等已在路线图中）。
• VS Code 扩展： VS Code 1.105.0 或更高版本。
• 独立 CLI： Node.js 20 或更高版本。
• Windows、Linux 或 macOS。

工作原理（简要）

Pixel Agents 通过两条路径检测 Claude Code 正在做什么：

1. 钩子模式（默认） — 钩子脚本接收 Claude 事件，如 SessionStart、PreToolUse、PermissionRequest 和 Stop，然后将经过身份验证的事件发送到任何活动的 Pixel Agents 服务器。
2. 启发式模式（后备） — 当钩子不可用时，它通过扫描 ~/.claude/projects/ 下的 Claude JSONL 会话记录来推断代理状态。

两个来源都被规范化为共享事件模型，运行时更新中央状态存储，办公室通过 Canvas 2D 渲染，并带有路径查找和角色状态机。

重要提示： Pixel Agents 不会修改 Claude Code 本身。其钩子配置位于 ~/.claude/ 下，其自身的持久数据位于 ~/.pixel-agents/ 下。

架构

代码库分为四个主要部分：

• core/ — 提供者、适配器、传输、模式和消息契约（无运行时副作用）。
• server/ — 共享 Fastify 服务器、代理运行时、持久化、Claude 提供者、转录扫描和独立 CLI。
• adapters/vscode/ — VS Code 适配器：终端、持久化和 webview 桥接。
• webview-ui/ — React 19、Vite、Canvas 2D，以及针对 VS Code 和浏览器 WebSocket 客户端的适配器特定传输。

设计是代理无关和编辑器无关的：类型化的 HookProvider 接口定义了集成边界，因此添加新的 AI 工具只需一个代码子目录。

安全说明（来自 README）

独立 CLI 会打印一个包含 ?token= 的 URL。该令牌是一种持有者能力 — 持有它的人可以从服务器可达的任何地方批准钩子安装并启动代理。请将 URL 视为机密：不要将其粘贴到共享渠道中，并注意它会出现在您的浏览器历史记录中。默认绑定地址是 127.0.0.1；绑定到 0.0.0.0 会将 UI 和 WebSocket 暴露给本地网络，并且只能在受信任的网络上进行。

许可证

MIT 许可证。