Petloop

English | 简体中文

English

Petloop is a desktop pet that reacts to your coding agent's status in real-time. Floating on your screen, it displays dynamic animations as AI agents execute tasks, await user approval, complete runs, or encounter errors.

It provides precise monitoring for OpenCode, Codex, and Antigravity, with activity inference or process detection for additional tools.

Quick Start

Requires Node.js 20 or higher.

Install globally and launch:

npm install --global petloop
petloop

Once launched, Petloop floats at the bottom-right corner of your screen and stays on top.

Alternative Run Methods

Run directly without installation:

npx petloop@latest

Or install as a project dependency:

npm install petloop
npx petloop

A drop-down source picker on the left of the pet allows you to monitor a specific AI coding tool or use "Auto Select". Task status is indicated by a floating indicator badge beside the pet.

Working with OpenCode

Launch OpenCode as usual—no need to modify prompts, install hooks, or configure static ports:

opencode .

Then start Petloop:

npx petloop

Petloop automatically:

1. Discovers running local OpenCode instances.
2. Verifies the local OpenCode server.
3. Subscribes to task event streams.
4. Falls back to read-only lifecycle log monitoring if the OpenCode TUI port is closed.
5. Reconnects automatically on OpenCode restarts or port changes.

Petloop never reads your prompts, source code, or AI responses.

Statuses

| Status | Pet Expression | Meaning | | --- | --- | --- | | idle | Quiet Idle | No active task | | running | Running & Working | Coding agent is executing a task | | waiting | Question Badge & Waiting | Waiting for user approval, input, or confirmation | | success | Celebrating Jump | Task completed successfully | | error | Shaking Warning | Task failed |

Supported AI Coding Tools

Support is divided into three levels:

| Level | Tools | Current capability | | --- | --- | --- | | Precise task state | OpenCode, OpenAI Codex, Antigravity | Uses explicit lifecycle events or structured local state | | Activity inference | Claude Code, Trae, Cursor, Windsurf, Gemini CLI, Cline, Roo Code, GitHub Copilot, JetBrains Junie | Infers task state from local session files and agent logs | | Process detection only | VS Code, JetBrains IDE, Zed, Aider, Continue, Tabnine, Amazon Q Developer, Sourcegraph Cody | Detects that the tool is running, but does not yet track task completion |

Cursor, Trae, Windsurf, and similar tools work through the shared PollingAdapter; they do not require separate adapters for basic activity feedback. Because their states are inferred from log activity, accuracy may change when a tool updates its log paths or formats.

A dedicated adapter is added only when a tool has a unique event API, structured state store, or lifecycle protocol that can provide more reliable task states.

Implementation details and monitoring flowcharts are documented in Technical Architecture.

Petloop only monitors the tool currently selected in the drop-down menu. It reads only the timestamps and lifecycle markers required to determine status, without saving or uploading log content.

Interactions

• Drag & Move: Press and hold the pet body to drag it freely across the screen.
• Click: Click the pet to re-trigger the current status speech bubble.
• Close: Hover over the pet window and click the close (X) button to exit.

Configuration

Specify OpenCode Server

Usually unnecessary. When connecting to a remote server or disabling auto-discovery:

npx petloop --opencode-url=http://127.0.0.1:4096

Or via environment variables:

OPENCODE_URL=http://127.0.0.1:4096 npx petloop

If the OpenCode Server requires HTTP Basic Auth:

OPENCODE_SERVER_USERNAME=opencode \
OPENCODE_SERVER_PASSWORD=your-password \
npx petloop

Custom Local State Port

Petloop provides a local HTTP state API at 127.0.0.1:17321 by default. To change the port:

PETLOOP_PORT=18000 npx petloop

Health check endpoint:

curl http://127.0.0.1:17321/health

Connecting Custom Coding Agents

Before official adapters are released, any local tool can push status updates directly to Petloop:

curl -X POST http://127.0.0.1:17321/state \
  -H 'Content-Type: application/json' \
  -d '{"state":"running","detail":"Running automated tests","source":"codex"}'

Payload format:

{
  "state": "idle | running | waiting | success | error",
  "detail": "Optional status detail",
  "source": "Optional tool identifier, e.g. codex, claude-code, cursor"
}

If PETLOOP_PORT was customized, update the endpoint URL accordingly.

Optional OpenCode Plugin

If auto-discovery and log monitoring are unavailable, you can install the bundled OpenCode plugin as a fallback.

Copy the plugin to OpenCode's global plugin directory:

mkdir -p ~/.config/opencode/plugins
cp node_modules/petloop/src/adapters/opencode/plugin.js \
  ~/.config/opencode/plugins/petloop.js

If Petloop uses a custom state port, specify it via:

PETLOOP_STATE_URL=http://127.0.0.1:18000/state opencode .

Restart OpenCode after installing the plugin. No plugin is required when auto-connection works.

Troubleshooting

Pet Remains Idle

Ensure OpenCode or your AI agent is running and has initiated a task. Completed past tasks will not show as running.

If using an explicit server URL, verify server health:

curl http://127.0.0.1:4096/global/health

npx petloop Fails to Launch

Check your Node.js version:

node --version

Petloop requires Node.js 20 or higher.

Cannot Connect to Local State API

Check if Petloop is running:

curl http://127.0.0.1:17321/health

If PETLOOP_PORT was modified, ensure you query the correct port.

Privacy

• Only monitors local task lifecycle statuses.
• Never reads or uploads source code.
• Never reads or uploads prompts or model responses.
• Does not take screenshots or use OCR.
• The local status server binds exclusively to 127.0.0.1.

Roadmap

Petloop plans to improve adapter accuracy and compatibility, expand precise task-state support, and add random and personal art pets.

See ROADMAP.md for details.

License

MIT

简体中文

Petloop 是一只会感知 coding agent 状态的桌面宠物。它悬浮在桌面上，在任务执行、等待确认、完成或失败时显示不同动画。

目前可精确监控 OpenCode、Codex 和 Antigravity，并为更多工具提供活动状态推断或进程检测。

快速开始

需要 Node.js 20 或更高版本。

全局安装并启动：

npm install --global petloop
petloop

启动后，Petloop 会显示在屏幕右下角并保持置顶。

其他运行方式

直接运行（无需安装）：

npx petloop@latest

或在项目中作为依赖安装：

npm install petloop
npx petloop

宠物左侧提供当前检测到的 AI coding IDE / agent 下拉选择器；可以选择只监控一个工具，或使用“自动选择”。任务状态以宠物旁边的小浮标显示。

配合 OpenCode 使用

正常启动 OpenCode 即可，不需要修改 prompt、安装 hook 或指定固定端口：

opencode .

再启动 Petloop：

npx petloop

Petloop 会自动：

1. 查找本机运行中的 OpenCode。
2. 发现并验证 OpenCode 的本地 Server。
3. 连接任务事件流。
4. 如果当前 OpenCode TUI 没有开放本地端口，则只读监听其生命周期日志。
5. OpenCode 重启或端口变化后自动重新连接。

Petloop 不会读取 prompt、源码或模型回复。

状态

| 状态 | 宠物表现 | 含义 | | --- | --- | --- | | idle | 安静待机 | 当前没有任务 | | running | 奔跑工作 | Coding agent 正在执行任务 | | waiting | 紫色问号和等待动画 | 等待用户授权、回答或确认 | | success | 跳跃庆祝 | 任务完成 | | error | 摇晃提示 | 任务失败 |

支持的 AI coding 工具

当前支持分为三个级别：

| 级别 | 工具 | 当前能力 | | --- | --- | --- | | 精确任务状态 | OpenCode、OpenAI Codex、Antigravity | 使用明确的生命周期事件或结构化本地状态 | | 活动状态推断 | Claude Code、Trae、Cursor、Windsurf、Gemini CLI、Cline、Roo Code、GitHub Copilot、JetBrains Junie | 根据本地会话文件和 agent 日志推断任务状态 | | 仅进程检测 | VS Code、JetBrains IDE、Zed、Aider、Continue、Tabnine、Amazon Q Developer、Sourcegraph Cody | 可以检测工具正在运行，但暂时不能追踪任务是否完成 |

Cursor、Trae、Windsurf 等工具直接使用通用 PollingAdapter，基础活动反馈不需要单独编写 adapter。由于状态来自日志活动推断，工具升级后如果日志路径或格式发生变化，准确度可能受到影响。

只有当工具提供独特的事件 API、结构化状态存储或生命周期协议，并能借此提高状态准确度时，才需要增加专用 adapter。

具体实现方式和监控流程图见 技术架构。

Petloop 只监控下拉列表当前选中的工具，仅读取判断状态所需的时间戳和生命周期标记，不保存或上传日志内容。

操作

• 按住宠物本体拖动，可以在屏幕内自由移动。
• 单击宠物可以再次查看当前状态。
• 鼠标移入窗口后，可以点击关闭按钮退出。

配置

指定 OpenCode Server

通常不需要设置。连接远程 Server 或关闭自动发现时，可以显式指定：

npx petloop --opencode-url=http://127.0.0.1:4096

也可以使用环境变量：

OPENCODE_URL=http://127.0.0.1:4096 npx petloop

如果 OpenCode Server 使用 HTTP Basic Auth：

OPENCODE_SERVER_USERNAME=opencode \
OPENCODE_SERVER_PASSWORD=your-password \
npx petloop

修改本地状态端口

Petloop 默认在 127.0.0.1:17321 提供本地状态接口。修改端口：

PETLOOP_PORT=18000 npx petloop

健康检查：

curl http://127.0.0.1:17321/health

连接其他 coding agent

在官方 adapter 发布前，任何本地工具都可以向 Petloop 推送统一状态：

curl -X POST http://127.0.0.1:17321/state \
  -H 'Content-Type: application/json' \
  -d '{"state":"running","detail":"正在执行测试","source":"codex"}'

请求格式：

{
  "state": "idle | running | waiting | success | error",
  "detail": "可选的状态说明",
  "source": "可选的工具标识，例如 codex、claude-code、cursor"
}

如果修改了 PETLOOP_PORT，请求地址也需要使用对应端口。

可选的 OpenCode 插件

自动发现和日志监听不可用时，可以安装包内提供的 OpenCode 插件作为降级方案。

将插件复制到 OpenCode 全局插件目录：

mkdir -p ~/.config/opencode/plugins
cp node_modules/petloop/src/adapters/opencode/plugin.js \
  ~/.config/opencode/plugins/petloop.js

如果 Petloop 使用了自定义状态端口，同时设置：

PETLOOP_STATE_URL=http://127.0.0.1:18000/state opencode .

安装插件后需要重新启动 OpenCode。自动连接正常时不需要安装插件。

常见问题

宠物一直显示空闲

确认 OpenCode 正在运行并已发起任务。旧任务如果已经结束，不会显示为运行中。

如果使用显式 Server 地址，可以检查：

curl http://127.0.0.1:4096/global/health

npx petloop 无法启动

确认 Node.js 版本：

node --version

Petloop 需要 Node.js 20 或更高版本。

无法连接本地状态接口

检查 Petloop 是否正在运行：

curl http://127.0.0.1:17321/health

如果设置了 PETLOOP_PORT，请使用修改后的端口。

OpenCode 等待授权时没有变化

不同 OpenCode 版本提供的事件可能不同。升级到最新 Petloop；如果自动方式仍无法识别，可以使用随包提供的 OpenCode 插件。

隐私

• 只监听本机任务生命周期状态。
• 不读取或上传源码。
• 不读取或上传 prompt 和模型回复。
• 不使用屏幕截图或 OCR 监控 IDE。
• 本地状态服务只绑定 127.0.0.1。

Roadmap

Petloop 计划继续提高 adapter 的准确度和兼容性、扩展精确任务状态支持，并加入随机及个人专属艺术宠物。

详情见 ROADMAP.md。

License

MIT