Clawd on Desk: A Pixel Crab That Watches Your AI Coding Agent
Project brief: A pixel desktop pet that watches Claude Code, Codex, Cursor & other AI coding agents, so you don't have to.
At a glance
- What is it?
- Clawd on Desk is a desktop pet that reacts to your AI coding agent's lifecycle events. It supports a long list of CLIs, takes different integration approaches for each, and has real limits you should check before adopting it.
- Who is it for?
- Adopt Clawd on Desk if you run Claude Code, Codex, or opencode daily and want a passive visual cue for long tasks. Skip it if you need reliable permission automation or if you use an agent with only state-only support, like Antigravity or Reasonix.
- Can I use it commercially?
- Yes, with strict conditions. AGPL-3.0 is a network copyleft licence: if people use a modified version over a network, for example as a hosted service, you must offer them its source code under the same licence.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly JavaScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What Clawd on Desk Actually Solves
When an AI coding agent runs a long task, you either stare at the terminal or walk away and lose track. Clawd on Desk puts a pixel crab on your desktop that changes its animation based on what the agent is doing. The README says it reacts in real time: thinking when you prompt, typing when tools run, grooving for subagents, reviewing permissions, celebrating on completion, and sleeping when you step away. The target user is a developer who runs Claude Code, Codex, or one of the other supported CLIs and wants a glanceable status without keeping a terminal window focused. It is not a monitoring dashboard or a logging tool. It is a visual companion that turns agent lifecycle events into a simple animation. The value is in not having to check the terminal repeatedly.
How the Integration Mechanism Varies by Agent
The project does not use one universal integration. Each agent gets a different mechanism, and the README is explicit about the differences. Claude Code gets full integration via command hooks plus HTTP permission hooks. Codex uses official hooks with a JSONL fallback from `~/.codex/sessions/`, auto-synced by default with real permission bubbles. Cursor Agent uses Cursor IDE hooks in `~/.cursor/hooks.json`. opencode and MiMo Code use plugin integrations that provide zero-latency event streaming and permission bubbles. Other agents are state-only: Antigravity, WorkBuddy, CodeWhale, Reasonix, and Pi only report lifecycle state and never pop a permission bubble. That distinction matters. If you want Clawd to approve or deny permission requests, you need an agent that supports the blocking hook. For state-only agents, Clawd is just an animation layer. The dynamic `/state` endpoint also lets you register a custom local executable and POST lifecycle events manually, but registration does not install hooks or make an arbitrary app report automatically.
Getting It Running: Installers and Hook Scripts
The README lists Windows 11, macOS, and Ubuntu/Linux as supported. Windows releases provide separate x64 and ARM64 installers. Source builds require Node.js. The actual installation commands are per-agent. For several agents you run a script from the project root. For example, Gemini CLI hooks are installed with `npm run install:gemini-hooks`, Antigravity with `npm run install:antigravity-hooks`, Cursor with `npm run install:cursor-hooks`, Kimi with `npm run install:kimi-hooks`, Qwen with `npm run install:qwen-hooks`, ZCode with `npm run install:zcode-hooks`, and CodeWhale with `npm run install:codewhale-hooks`. For CodeBuddy you run `node hooks/codebuddy-install.js`, for WorkBuddy `node hooks/workbuddy-install.js`, and for opencode `node hooks/opencode-install.js`. The Kiro integration is different: it injects hooks into custom agent configs under `~/.kiro/agents/` and creates a `clawd` agent that is re-synced from Kiro's built-in `kiro_default`. You then opt in with `kiro-cli --agent clawd` or `/agent swap clawd`. The README also mentions installing some integrations from Settings → Agents in the app UI. The variety means you cannot rely on a single install command.
A Real Limitation: State-Only Agents and Permission Gaps
The biggest limitation is that not all agents get the same treatment. The README explicitly says Antigravity is state-only: Clawd never pops a permission bubble for agy, and every Allow or Deny choice happens in agy's own terminal menu. WorkBuddy is also state plus notification only, because the desktop app resolves permissions in its own native sandbox. CodeWhale and Reasonix are Phase 1 state-only, meaning they drive animations but no permission bubbles and no subagent tracking. If you use one of these agents and expect Clawd to handle permission prompts, it will not. Another gap: opencode and MiMo Code child sessions spawned by the `task` tool are headless and do not participate in the visible multi-session animation fanout. So if you rely on subagents, you will not see them reflected in the pet. The project is honest about these limits, but they are easy to miss if you only look at the headline feature list.
Custom Themes and Imported Animation Packs
The pet is not locked to the crab. It ships with three built-in themes: Clawd (pixel crab), Calico (a calico cat), and Cloudling (a cloud creature). The README says it has full support for custom themes and for imported Codex Pet animation packs. That is a meaningful feature if you already use Codex Pet packs and want the same visual language on your desktop. The custom theme support means you can replace the sprite set with your own pixel art, which fits the open-source ethos. The README does not describe the theme format in detail, so you will need to inspect the repository or existing themes to learn the file structure. The fact that it accepts Codex Pet packs suggests the animation format is compatible or convertible, but the exact conversion path is not documented in the provided material.
Maintenance and Upgrade Cost
The repository has recent releases: v0.16.0 from 2026-08-23, v0.15.0 from 2026-08-13, and a diagnostic build for issue #813. That suggests active development. The diagnostic build naming (diag-813) indicates the maintainers ship builds for specific bug reports, which is a sign of responsive maintenance. The cost comes from the many integration points. Each agent has its own hook config file and installation script. When an agent like Codex or Cursor changes its hook schema, Clawd's integration can break. You will need to update Clawd to match. The README also mentions preserving explicit global or per-hook `enabled:false` settings for ZCode, which shows the project tries to avoid clobbering user config, but it also means you should check your hook files after an update to ensure nothing changed unexpectedly. The license is AGPL-3.0, which has implications if you modify and distribute the code, but that is a legal question you should resolve with your own counsel.
Alternatives and the Difference in Approach
The closest alternative is the built-in status indicators in each agent's own terminal UI. Claude Code, Codex, and Cursor all show some progress in their interfaces. The difference is that Clawd on Desk is a separate always-visible layer that does not require you to keep a terminal window in view. Another alternative is a custom script that watches agent log files or session directories and sends notifications, but that requires you to build and maintain the parsing logic yourself. Clawd on Desk ships those parsers for many agents, which is its main advantage. The trade-off is that a self-built script can be tailored to your exact workflow, while Clawd's generic hooks may not cover every edge case, especially for state-only agents. If you use only one agent and are comfortable writing a small watcher, you might not need Clawd. If you use several agents, the prebuilt integrations save time.
Who Should Adopt It and What to Verify First
Adopt Clawd on Desk if you are a daily user of Claude Code, Codex, or opencode and want a passive visual cue for long tasks. The full integration with permission bubbles makes it useful for those agents. Skip it if you rely on Antigravity, WorkBuddy, or Reasonix for permission handling, because Clawd will not cover that. Before installing, verify that your exact agent version is compatible, since hooks and config paths change. Check the README's per-agent guide for your specific CLI, and confirm the install script matches your OS. Also verify that the theme format works with your custom assets if you plan to import Codex Pet packs. Finally, review the AGPL-3.0 license if you plan to modify the code for internal distribution. The project is active, but the breadth of integrations means you should test the specific agent you use before relying on it in daily work.
Editorial conclusion
Adopt Clawd on Desk if you run Claude Code, Codex, or opencode daily and want a passive visual cue for long tasks. Skip it if you need reliable permission automation or if you use an agent with only state-only support, like Antigravity or Reasonix. Before adopting, verify that your exact agent version and OS (Windows 11, macOS, Ubuntu) are covered, and check whether the hook installation method for your agent has changed. Also confirm that the AGPL-3.0 license fits your use, especially if you embed or modify the code. Start with the built-in Clawd theme, then test a custom theme or an imported Codex Pet pack before relying on it in daily work.
Community notes