Clawd on Desk: a desktop pet that mirrors your AI coding agent

What Clawd on Desk actually watches

The problem it addresses is attention, not automation. When a coding agent runs a long task, the terminal gives you no reason to look at it until something finishes or blocks. Clawd on Desk puts a small animated character on the desktop and drives its animation from the agent's lifecycle events, so a glance replaces a context switch. The README frames it as: start a long task, walk away, come back when the crab tells you it is done.

The intended user is someone running an agent interactively on their own machine. The README lists Windows 11, macOS and Ubuntu/Linux, with separate x64 and ARM64 installers for Windows. Source builds require Node.js. It is not a server component, and there is no documented headless mode, so a CI runner or an SSH session is outside its scope.

The supported agent list is unusually long. Beyond Claude Code and Codex CLI it names Copilot CLI, Gemini CLI, Antigravity CLI, Cursor Agent, CodeBuddy, WorkBuddy, Kiro CLI, Kimi Code CLI, Qwen Code, ZCode, CodeWhale, opencode, MiMo Code, Pi, OpenClaw, Hermes Agent, Qoder, QoderWork, QwenWork, Reasonix CLI, DeepSeek Harness and TraeCode. That breadth is the main differentiator, but the integrations are not equivalent, and the README is explicit about which are state-only.

Hooks, JSONL fallback and the state pipeline

Clawd on Desk does not read your agent's output stream. It receives events. For most agents, the installer writes command hooks into that agent's own configuration file, and the agent invokes them at lifecycle points such as prompt submission, tool execution, notification and completion. The pet maps those events to animations: thinking when you prompt, typing when tools run, reviewing permissions, celebrating on completion, sleeping when you step away.

Codex CLI is the exception worth noting. The README describes official hooks with a JSONL fallback under `~/.codex/sessions/`, auto-synced by default, plus real permission bubbles. That fallback matters because it means Codex integration can degrade to reading session logs rather than requiring hook registration to succeed.

Permission handling splits the integrations into two classes. Claude Code uses command hooks plus HTTP permission hooks. CodeBuddy and Qwen Code also support permission request bubbles. opencode and MiMo Code use a plugin integration and support Allow, Always and Deny from the bubble. ZCode registers blocking permission hooks and will not register over a foreign `PermissionRequest` hook. Against that, Antigravity CLI is described as state-only: Clawd never pops a permission bubble for it, and every Allow, Deny or Always-allow choice happens in agy's own terminal menu. CodeWhale, Reasonix CLI, Pi, WorkBuddy and the generic custom HTTP agent are likewise state-only or state plus notification. The custom HTTP path is the most limited: you register a local executable in Settings, it POSTs lifecycle events to a dynamic `/state` endpoint, and registration does not install hooks or make an arbitrary application report anything by itself.

Installing Clawd on Desk and running it the first time

The README points at the releases page for prebuilt installers, with separate x64 and ARM64 NSIS installers on Windows and dmg or zip builds on macOS. If you prefer to run from source, the repository is an Electron app and the package manifest defines the entry point. After cloning, install dependencies and start it:

npm install
npm start

`npm start` runs `node launch.js`, which is the documented entry point. The `postinstall` script runs `node scripts/verify-electron-install.js`, so a broken Electron download surfaces during install rather than at first launch. On first run you should see the pet window appear on the desktop.

Agent integrations are installed from Settings, under the Agents section, or from the command line. For Claude Code the script is:

npm run install:claude-hooks

Other agents follow the same pattern with their own script names, for example `npm run install:gemini-hooks`, `npm run install:cursor-hooks`, `npm run install:kimi-hooks`, `npm run install:qwen-hooks`, `npm run install:zcode-hooks` and `npm run install:pi-extension`. A few integrations use a plain node call instead, such as `node hooks/codebuddy-install.js`, `node hooks/workbuddy-install.js` and `node hooks/opencode-install.js`.

The first real test is to start your agent, submit a prompt, and watch the pet change state. If it stays idle, the hook did not land. The README documents the target files so you can check by hand: Copilot CLI uses `~/.copilot/hooks/hooks.json`, Gemini CLI uses `~/.gemini/settings.json`, Cursor Agent uses `~/.cursor/hooks.json`, Kimi Code CLI uses `~/.kimi/config.toml` with `[[hooks]]` entries, and Qwen Code uses `~/.qwen/settings.json`. Themes are a separate axis; the app ships with Clawd, Calico and Cloudling, and the manifest exposes `npm run create-theme` for custom themes plus import of Codex Pet animation packs.

Where the integration model breaks down

The state-only integrations are the first real limitation, and the README does not hide them. CodeWhale is Phase 1 only: idle, thinking, working, sleeping, error, attention and sweeping animations, with no permission bubbles and no subagent tracking. Reasonix CLI is similarly state-only and leaves permission decisions in its own terminal flow. Pi is state-only and preserves Pi's default YOLO behavior, which means the pet will never be the thing that stops a risky command.

Subagent visibility is uneven. opencode and MiMo Code stream events with low latency and support permission bubbles, but the README states that child sessions spawned by the `task` tool are headless and do not participate in the visible multi-session animation fanout. If your workflow leans on subagents, the pet shows you less than you might expect.

Registration is also not guaranteed to be non-destructive. ZCode integration preserves explicit global or per-hook `enabled:false` settings and refuses to register over a foreign `PermissionRequest` hook, which is a sensible guard, but it implies the installer is editing files that other tools also own. The same is true of every settings file in the list above. A hook written into `~/.gemini/settings.json` or `~/.cursor/hooks.json` is your configuration, and the README does not document a rollback beyond the uninstall script that exists for Claude Code (`npm run uninstall:claude-hooks`). For the others, plan on editing the JSON yourself if you want out.

Finally, this is a desktop application. It needs a graphical session, and the README gives no headless or remote mode. On a build server it has nothing to display.

Compared with watching the terminal or a notification hook

The obvious alternative is doing nothing: keep the agent's terminal visible and read it. That costs no installation and no configuration edits, and it works everywhere, including remote shells. Its weakness is exactly the case Clawd on Desk targets, which is a task long enough that you leave the window.

A lighter alternative is a notification hook that fires a system notification when the agent finishes or needs input. That is a few lines in the same settings file Clawd on Desk would edit, and it carries no runtime. The difference is persistence and granularity. A notification tells you once, at the end. Clawd on Desk holds a continuous state, so you can see at a glance whether the agent is thinking, running tools, waiting on a permission prompt or finished, without having received a message. Whether that continuous signal is worth an Electron process and a set of hook edits is the actual decision.

A third option is a terminal multiplexer with a status line, which keeps everything inside the terminal and survives over SSH. It reports what the multiplexer knows, not what the agent is doing, so the two are not substitutes.

Licence, packaging and what upgrades cost you

The project is licensed AGPL-3.0, and the repository carries a NOTICE.md alongside the LICENSE file. AGPL-3.0 is a strong copyleft licence with a network clause. For an end user running the desktop app, the practical effect is that you receive the source. For anyone who wants to embed Clawd on Desk in a hosted product, the network clause is the part to read carefully, and the safest statement is that this is a question for your own legal review rather than something this article can settle.

The upgrade surface is larger than the app itself. Installing an integration edits another tool's configuration, and those files can be rewritten by the agent vendor. The README already documents a legacy path for WorkBuddy (`~/.workbuddy/settings.json` versus the current `~/.workbuddy-ai/settings.json`) and an effective-file resolution order for opencode and MiMo Code, where later files win. That kind of churn means an upgrade can silently change which config file is authoritative. The package manifest also carries verification scripts such as `npm run verify:release`, `npm run verify:updater-metadata` and `npm run verify:winget-arch`, which suggests the maintainers take packaging correctness seriously, but they do not verify your local hook state after an agent updates itself.

The repository is not archived. The most recent push recorded is 2026-08-23, the same date as the v0.16.0 release, with v0.15.0 on 2026-08-13 and a diagnostic build tagged diag-813 on 2026-08-17. That is an active release cadence rather than a frozen project, but it also means configuration details can move between versions.

Editorial conclusion

Adopt Clawd on Desk if you already run one of the supported agents in a terminal and want an ambient signal for long tasks, and you are comfortable with the installer writing hook configuration into that agent's own settings file. Do not adopt it if you want a tool that controls agents, or if you run agents in CI or on remote machines where no desktop exists. Before installing anything, open Settings and Agents and check which of your agents is listed as state-only rather than permission-capable, because those two groups behave very differently.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes