Petlaude

Imported from zuoqiumama/Petlaude (AGENTS.md). Install upstream with npx skills add zuoqiumama/Petlaude. Copyright stays with the author.

AGENTS.md

This file is the entry point for coding agents working in this repository. Keep it short and operational. Deep background lives in docs/project/.

Project Overview

Clawd 是一个 Electron 桌宠：通过 hook、日志轮询、plugin 和 extension 感知 AI coding agent 的工作状态，并播放像素风动画。当前支持 Claude Code、Codex CLI、Copilot CLI、Gemini CLI、Antigravity CLI (agy)、Cursor Agent、CodeBuddy、Kiro CLI、Kimi Code CLI (Kimi-CLI)、Qwen Code、opencode、Pi、OpenClaw、Hermes Agent；内置 Clawd / Calico / Cloudling 三套主题，支持用户主题；平台覆盖 Windows、macOS、Linux，UI 支持 en / zh / ko / ja。

Common Commands

npm start
npm run build
npm run build:win:x64
npm run build:win:arm64
npm run build:win:all
npm run build:mac
npm run build:linux
npm run build:all
npm install
npm test
npm run create-theme

npm run install:claude-hooks
npm run uninstall:claude-hooks
npm run install:cursor-hooks
npm run install:gemini-hooks
npm run install:antigravity-hooks
npm run install:kiro-hooks
npm run install:kimi-hooks
npm run install:qwen-hooks
npm run install:pi-extension
npm run uninstall:pi-extension
npm run install:openclaw-plugin
npm run uninstall:openclaw-plugin
npm run install:hermes-plugin
npm run uninstall:hermes-plugin
npm run install:codex-hooks
npm run uninstall:codex-hooks
npm run install:codex-debug-hooks
npm run uninstall:codex-debug-hooks
node hooks/codebuddy-install.js
node hooks/opencode-install.js

bash scripts/remote-deploy.sh user@host
bash test-demo.sh [seconds]
bash test-mini.sh [seconds]
bash test-macos.sh
bash test-oneshot-gate.sh [state] [seconds]

正常启动时，Clawd 只会为已启用的 agent 自动同步 Claude / Codex / Copilot / Gemini / Antigravity / Cursor / CodeBuddy / Kiro / Kimi / Qwen hooks、opencode / OpenClaw / Hermes plugins 和 Pi extension。禁用 agent 会跳过启动同步并屏蔽事件/权限入口，但不会卸载用户已有 hooks / plugins / extensions；从 Settings 重新启用时会对该 agent 做一次 integration sync。手动安装命令主要用于调试、重装或远程部署。 Copilot CLI 同步走 <COPILOT_HOME 或 ~/.copilot>/hooks/hooks.json，marker-based 增量合并只接管含 copilot-hook.js 标记的条目，用户其他 entry / 其他 hooks/*.json 文件原样保留；hooks.json 或 settings.json 顶层 disableAllHooks: true 时 doctor 报 warning（不挂 Fix 按钮）。详见 docs/guides/copilot-setup.md。

Read These Docs

• docs/project/project-introduction.md：5 分钟了解项目定位、状态映射和目录结构
• docs/project/agent-runtime-architecture.md：集成方式、数据流、多 agent、permission bubble、opencode、终端聚焦、自动同步
• docs/project/project-architecture.md：更完整的模块边界和启动/运行时分层
• docs/project/theme-state-ui.md：状态机、主题系统、settings、mini mode、素材规则、平台限制、待落地 UI 决策
• docs/project/release-process.md：发版 checklist、release note 核对、tag 触发 GitHub 打包和资产确认
• docs/guides/copilot-setup.md：Copilot CLI 自动同步说明、COPILOT_HOME 兼容性、手动配置备选模板
• docs/guides/state-mapping.md：状态 → 动画权威表
• docs/guides/guide-theme-creation.md：主题作者指南
• docs/guides/setup-guide.md：安装、远程 SSH、各 agent 接入
• docs/guides/known-limitations.md：用户向已知限制
• docs/guides/codex-wsl-clarification.md：Codex / WSL 路径与 Node 说明

Runtime Summary

• 事件主路径：hook / log monitor → src/server.js → src/state.js → IPC → src/renderer.js
• 桌宠采用双窗口模型：渲染窗口只负责显示；输入窗口负责 pointer 事件和拖拽
• 多会话 UI 主路径：src/state.js 生成 session snapshot → Dashboard / Session HUD；HUD 贴近桌宠显示当前 live session，Dashboard 负责详情、别名和跳转终端
• src/server.js 启动后会为已启用 agent 异步同步缺失 hooks / plugins；Codex official hooks 为 primary，JSONL 轮询保留为 fallback
• src/server.js 只在 Claude Code 已启用且 manageClaudeHooksAutomatically 打开时 watch ~/.claude/settings.json，并在 hook 被抹掉时自动重装
• src/agent-gate.js 控制各 agent 的启用状态、权限气泡开关和 wait-for-input notification 子开关
• 设置系统主链路是 src/prefs.js → src/settings-controller.js → src/settings-store.js，写入 side effects 收敛在 src/settings-actions.js
• 启动时还会尝试自动安装 VS Code / Cursor terminal-focus extension，并初始化 updater
• 远程场景依赖 Settings Remote SSH runtime / deploy 路径、scripts/remote-deploy.sh CLI 备选和 SSH 反向端口转发

Core Files

更细的背景见 docs/project/agent-runtime-architecture.md 和 docs/project/theme-state-ui.md。

Constraints

• Claude Code / CodeBuddy 的阻塞式权限审批走 POST /permission HTTP hook；普通状态事件走 command hook
• Codex 的阻塞式权限审批走 official PermissionRequest command hook：hook 脚本长连接 POST /permission，只允许 stdout 返回 sanitized behavior/message，updatedInput / updatedPermissions / interrupt 必须 omit
• hook 脚本只允许依赖 Node 内置模块，以及同目录的 server-config.js、shared-process.js、json-utils.js、codex-subagent-fields.js
• hook 脚本需要稳定终端 PID 时，必须走 getStablePid() 进程树解析；不要用 process.ppid 做简化替代
• opencode 权限不走 permission.ask hook，而是 event hook + reverse bridge
• Pi 通过 ~/.pi/agent/extensions/clawd-on-desk 的 global extension 推送状态；Clawd 对 Pi 是 state-only，不接管权限、不弹权限气泡，也不把 Pi 的默认 YOLO 流程改成手动确认
• OpenClaw 通过 ~/.openclaw/openclaw.json plugin 路径做 state-only 集成；Phase 1 不做 permission bubble / terminal focus，主要支持本地 openclaw tui --local
• Antigravity CLI (agy) 通过 ~/.gemini/config/hooks.json 做 state-only hook 集成（PreInvocation / PostToolUse / PostInvocation / Stop），不注册 PreToolUse。agy LLM 会主动调内置 ask_permission 工具，触发 agy 自己的 5 选项 native menu（含 "Persist to settings.json" 持久白名单），Clawd 不插手权限决策也不双层确认。agents/antigravity-cli.js capabilities.permissionApproval / interactiveBubble 均为 false。
• Qwen Code 通过 ~/.qwen/settings.json 做 hook-only 集成（SessionStart / SessionEnd / UserPromptSubmit / PreToolUse / PostToolUse / Stop / Notification / PermissionRequest），支持状态与阻塞式 PermissionRequest 权限气泡；disableAllHooks: true 时注册条目不会触发。
• HTTP 服务端口范围固定为 127.0.0.1:23333-23337；运行时端口写入 ~/.clawd/runtime.json
• Remote SSH 的远端 Node 探测要求 Node >= 14；scripts/remote-deploy.sh 与 src/remote-ssh-node.js 的 probe 顺序、候选路径、版本判断和输出字段必须保持行为对齐
• 注册 Claude Code hook 时只能追加，不能覆盖用户已有 hook 数组
• Copilot CLI hooks 走自动同步：hooks/copilot-install.js 在本地启动和 scripts/remote-deploy.sh --remote 两路都被调用；路径解析尊重 COPILOT_HOME env（trimmed 非空才生效，否则 fallback 到 ~/.copilot）；hooks/copilot-hook.js 的 session-state resolver 同样走 env
• 禁用 agent 不应卸载 hooks / plugins / extensions：只停止对应 monitor、清理 session / bubble、让 HTTP hook 入口快速 fallback；重新启用才触发一次 integration sync
• Kiro 的 sessionId="default" 会复用；session alias key 必须按 cwd scope 区分，同时保留旧 local|kiro-cli|default 只读 fallback
• Windows NSIS release 必须产出明确架构的 x64 / ARM64 安装包：win.artifactName 保留 ${arch}，nsis.buildUniversalInstaller 保持 false
• 资源路径统一用 path.join(__dirname, ...)
• 需要编辑发布素材时，先复制到 assets/source/ 再改，不要直接改工作素材来源不明的文件
• assets/source/cloudling-pointer-bridge/ 是 Cloudling 指针桥素材的保留源文件目录；运行时逻辑已内联进主题 SVG，不要把这个 source 目录当临时文件清理
• 主题状态、sleep/DND、mini mode、状态映射的细节在 docs/project/theme-state-ui.md
• Settings 体系里，store 是唯一真相，controller 是唯一写入者；不要绕开 settings-controller.js

Testing

• 自动化测试使用 Node 内置 test runner：npm test
• 当前 test/*.test.js 已覆盖 hooks/installers、agent registry、server state/permission 路由、state、theme-loader / overrides、settings、menu、tick、Dashboard、session HUD、session alias、update bubble、updater、remote-deploy、remote-ssh runtime / deploy / profile / node / IPC、work-area / visible margins 等纯逻辑模块
• 当前开发环境是 Windows-first；macOS 特定路径无法在这里手动 QA，改到 mac 逻辑时要用 code-review-first 的方式说明行为变化和残余风险
• 涉及 Claude Code hook payload 的改动（尤其 /permission、permission_suggestions、updatedPermissions、elicitation 输入）至少用一次真实 Claude Code 验证；curl 自编 payload 不够
• 透明窗口、托盘、真实拖拽、跨平台前台聚焦等 Electron 行为仍以手动验证为主

High-Risk Gotchas

• hitWin.focusable = true 是修复 Windows 拖拽 bug 的关键，不要轻易改回去
• miniTransitioning 期间，所有窗口定位路径都必须先检查保护标志，否则 setPosition() 可能并发崩
• DND 会屏蔽 hook 事件并压住 bubble，但不应替用户做权限决定：opencode 走 silent drop 回到 TUI 提示，Claude Code / CodeBuddy 走断连回到内置聊天/终端确认，Codex official hook 走 no-decision {} 回到原生审批提示；Pi 是 state-only，不进入权限审批链路
• Session HUD 显示所有非 headless、非 sleeping 的 live session，包括 badge=Done 的 idle session；不要再按 state !== "idle" 过滤，否则完成后的 Claude Code 会话会从 HUD 消失
• update bubble 跟随桌宠时要同时避让 Session HUD 和 permission stack；permission bubble 增删、测高、deny-and-focus 后都要触发 update bubble 重排
• mini-working 是可选主题能力，缺失时必须优雅降级
• contextMenuOwner 必须保留 parent: win；配合 closable:false 才不会把退出流程卡死
• Windows 前台窗口锁依赖 ALT trick + koffi FFI；相关回归通常不是单点逻辑 bug
• ~/.claude/settings.json 的 hook 恢复 watcher 必须盯目录而不是文件；原子替换会让文件级 watch 在 Windows 上静默失效
• Claude watcher 必须同时受 manageClaudeHooksAutomatically 和 claude-code.enabled 保护；不要让禁用 Claude Code 后的 watcher 重新写回 hooks
• opencode 的 permission.ask hook 目前不可用，权限只能走 event hook + bridge
• Codex CLI official hooks 已接入；JSONL 轮询仍是 fallback，用于 hook 不可用、hook 未覆盖事件（如 WebSearch / compaction / abort）和历史兼容。Windows command 必须用 PowerShell & "node" ... 格式，裸 "node" "hook.js" 会 exit 1
• Kiro 没有 global hooks，只能注入到 ~/.kiro/agents/*.json
• src/renderer.js 里给 <img> SVG 追加的 ?_t= cache-bust query 不能删；Chromium 会复用同 URL SVG 的动画时间线，一次性动画会停在末帧

Do Not Revisit

Language 子菜单底部截断是 Electron 透明窗口 + Windows DWM 的底层兼容问题。不要再尝试通过切换 alwaysOnTop、透明窗策略或 JS 菜单布局修它。