Clawd on Desk

_{🌏 Don't see your language? Open a PR to add one — Español, Français, Deutsch, etc. all welcome.}

Clawd lives on your desktop and reacts to what your AI coding agent is doing — in real time. Start a long task, walk away, come back when the crab tells you it's done. Thinking when you prompt, typing when tools run, grooving or juggling for subagents, reviewing permissions, celebrating when tasks complete, sleeping when you step away. Ships with three built-in themes: **Clawd** (pixel crab), **Calico** (三花猫), and **Cloudling** (云宝), with full support for custom themes and imported Codex Pet animation packs. > Supports Windows 11, macOS, and Ubuntu/Linux. Windows releases provide separate x64 and ARM64 installers. Source builds require Node.js. Works with **Claude Code**, **Codex CLI**, **Copilot CLI**, **Gemini CLI**, **Cursor Agent**, **CodeBuddy**, **Kiro CLI**, **Kimi Code CLI (Kimi-CLI)**, **opencode**, **Pi**, **OpenClaw**, and **Hermes Agent**. ## Features ### Multi-Agent Support - **Claude Code** — full integration via command hooks + HTTP permission hooks - **Codex CLI** — official hooks with JSONL fallback (`~/.codex/sessions/`), registered automatically with real permission bubbles - **Copilot CLI** — command hooks via `~/.copilot/hooks/hooks.json` - **Gemini CLI** — command hooks via `~/.gemini/settings.json` (registered automatically when Clawd starts, or run `npm run install:gemini-hooks`) - **Cursor Agent** — [Cursor IDE hooks](https://cursor.com/docs/agent/hooks) in `~/.cursor/hooks.json` (registered automatically when Clawd starts, or run `npm run install:cursor-hooks`) - **CodeBuddy** — Claude Code-compatible command hooks + HTTP permission hooks via `~/.codebuddy/settings.json` (registered automatically when Clawd starts, or run `node hooks/codebuddy-install.js`) - **Kiro CLI** — command hooks injected into custom agent configs under `~/.kiro/agents/`, plus an auto-created `clawd` agent that is re-synced from Kiro's built-in `kiro_default` whenever Clawd starts, so you can opt into hooks with minimal behavior drift via `kiro-cli --agent clawd` or `/agent swap clawd` (registered automatically when Clawd starts, or run `npm run install:kiro-hooks`). State hooks are verified on macOS and Windows. - **Kimi Code CLI (Kimi-CLI)** — command hooks via `~/.kimi/config.toml` (`[[hooks]]` entries) (registered automatically when Clawd starts, or run `npm run install:kimi-hooks`) - **opencode** — [plugin integration](https://opencode.ai/docs/plugins) via `~/.config/opencode/opencode.json` (registered automatically when Clawd starts); zero-latency event streaming, permission bubbles with Allow/Always/Deny, and building animations when parallel subagents are spawned via the `task` tool - **Pi** — global extension via `~/.pi/agent/extensions/clawd-on-desk` (registered automatically when Clawd starts, or run `npm run install:pi-extension`); interactive lifecycle updates plus permission bubbles for `bash` / `write` / `edit` tool calls, with Pi terminal confirmation fallback - **OpenClaw** — state-only plugin integration via `~/.openclaw/openclaw.json` (registered automatically when an OpenClaw config already exists, or run `npm run install:openclaw-plugin`); local `openclaw tui --local` sessions drive Clawd animations, without permission bubbles or terminal focus in Phase 1 - **Hermes Agent** — [plugin integration](https://hermes-agent.org/) via Hermes' managed plugin directory (registered automatically when Hermes is installed, or run `npm run install:hermes-plugin`); state, sessions, SessionEnd, and terminal focus are supported - **Multi-agent coexistence** — run all agents simultaneously; Clawd tracks each session independently ### Animations & Interaction - **Real-time state awareness** — agent hooks and log polling drive Clawd's animations automatically - **12 animated states** — idle, thinking, typing, building, subagent groove, multi-subagent juggling, error, happy, notification, sweeping, carrying, sleeping - **Codex Pet imports** — import Codex Pet zip packages from `Settings…` → `Theme`; Clawd adapts their atlas animations into managed themes - **Eye tracking** — Clawd follows your cursor in idle state, with body lean and shadow stretch - **Sleep sequence** — yawning, dozing, collapsing, sleeping after 60s idle; mouse movement triggers a startled wake-up animation - **Click reactions** — double-click for a poke, 4 clicks for a flail - **Drag from any state** — grab Clawd anytime (Pointer Capture prevents fast-flick drops), release to resume - **Mini mode** — drag to right edge or right-click "Mini Mode"; Clawd hides at screen edge with peek-on-hover, mini alerts/celebrations, and parabolic jump transitions ### Permission Bubble - **In-app permission review** — when Claude Code, Codex CLI, CodeBuddy, opencode, or Pi request tool permissions, Clawd pops a floating bubble card instead of waiting in the terminal - **Allow / deny / agent-native extras** — one-click approve or reject, plus permission rules / `Always` actions when the source agent supports them - **Global hotkeys** — `Ctrl+Shift+Y` to Allow, `Ctrl+Shift+N` to Deny the latest permission bubble (only registered while bubbles are visible) - **Stacking layout** — multiple permission requests stack upward from the bottom-right corner - **Auto-dismiss** — if you answer in the terminal first, the bubble disappears automatically - **Per-agent toggle** — open `Settings…` → `Agents`, pick an agent, and turn off `Show pop-up bubbles` to keep prompts in that agent's own terminal/TUI ### Session Intelligence - **Multi-session tracking** — sessions across all agents resolve to the highest-priority state - **Subagent awareness** — headphones groove for 1 subagent, three-ball juggling for 2+ - **Sessions dashboard + HUD** — right-click or tray → `Open Dashboard` to inspect live sessions, recent events, aliases, and jump to a terminal; a compact HUD near Clawd keeps current live sessions visible - **Terminal focus** — Dashboard/HUD actions jump to a specific session's terminal window; notification/attention states auto-focus the relevant terminal - **Process liveness detection** — detects crashed/exited supported agent processes and cleans up orphan sessions - **Startup recovery** — if Clawd restarts while any supported agent is still running, it stays awake instead of falling asleep ### System - **Click-through** — transparent areas pass clicks to windows below; only Clawd's body is interactive - **Position memory** — Clawd remembers where you left it across restarts (including mini mode) - **Single instance lock** — prevents duplicate Clawd windows - **Auto-start** — Claude Code's SessionStart hook can launch Clawd automatically if it's not running - **Do Not Disturb** — right-click or tray menu to enter sleep mode; all hook events are silenced until you wake Clawd. Permission bubbles are suppressed during DND — Codex and opencode fall back to their native prompts, Pi falls back to terminal confirmation, while Claude Code and CodeBuddy fall back to their built-in permission flow - **Sound effects** — short audio cues on task completion and permission requests (toggle via right-click menu; 10s cooldown, auto-muted during DND) - **System tray** — resize (S/M/L), DND mode, language switch, auto-start, check for updates - **i18n** — English, Simplified Chinese, Traditional Chinese, Korean, and Japanese UI; switch via right-click menu or tray - **Auto-update** — checks GitHub releases; Windows installs NSIS updates on quit, macOS/Linux `git pull` + restart when running from a cloned repo ## Animations

_Idle	_{Thought Bubble}	_Typing	_Building	_{1 Subagent}	_{2+ Subagents}
_{Calico Idle}	_{Calico Thinking}	_{Calico Typing}	_{Calico Building}	_{Calico Juggling}	_{Calico Conducting}
_{Cloudling Idle}	_{Cloudling Thinking}	_{Cloudling Typing}	_{Cloudling Building}	_{Cloudling Juggling}	_{Cloudling Conducting}

Full event-to-state mapping, mini mode, and click reactions: **[docs/guides/state-mapping.md](docs/guides/state-mapping.md)** ## Multi-display Clawd adapts to multi-monitor setups: proportional sizing uses the display Clawd launches on, portrait monitors get a bounded boost so the pet stays readable on tall narrow screens, and you can drag Clawd across displays.

_{Want to see the real multi-monitor behavior? Watch the demo video in this repository.}

## Quick Start For normal use, download the latest prebuilt installer from **[GitHub Releases](https://github.com/rullerzhou-afk/clawd-on-desk/releases/latest)**: - **Windows**: `Clawd-on-Desk-Setup--x64.exe` or `Clawd-on-Desk-Setup--arm64.exe` - **macOS**: `.dmg` - **Linux**: `.AppImage` or `.deb` Launch Clawd after installing it; supported agent hooks/plugins are synced automatically on startup. Run from source only if you're contributing, testing unreleased code, or debugging integrations. Source installs download Electron/build tooling and can create a large `node_modules` tree. ```bash # Clone the repo git clone https://github.com/rullerzhou-afk/clawd-on-desk.git cd clawd-on-desk # Install dependencies npm install # Start Clawd (auto-registers Claude Code hooks on launch) npm start ``` **Claude Code** and **Codex CLI** work out of the box with auto-registered hooks. **Gemini CLI**, **Cursor Agent**, **CodeBuddy**, **Kiro CLI**, **Kimi Code CLI (Kimi-CLI)**, **opencode**, **Pi**, **OpenClaw**, and **Hermes Agent** auto-register when Clawd launches (if they're installed; OpenClaw also needs an initialized config). **Copilot CLI** still needs one-time hook setup. Also covers remote SSH, WSL, and platform-specific notes (macOS / Linux): **[docs/guides/setup-guide.md](docs/guides/setup-guide.md)** For the official `Codex + WSL` status, Clawd's current implementation boundary, and why this is easy to misread, see: **[docs/guides/codex-wsl-clarification.md](docs/guides/codex-wsl-clarification.md)** ## Known Limitations Some agents have feature gaps (no permission bubble, polling latency, no terminal focus). See the full table: **[docs/guides/known-limitations.md](docs/guides/known-limitations.md)** ## Custom Themes Clawd supports custom themes — replace the default crab with your own character and animations. If you already have a Codex Pet package, import its zip from `Settings…` → `Theme` → `Import pet zip`; Clawd turns the atlas into a managed theme automatically. **Quick start:** 1. Scaffold a theme: ```bash node scripts/create-theme.js my-theme # or npm run create-theme -- my-theme ``` No argument also works: it creates the next available `my-theme` scaffold in your user themes directory. 2. Edit `theme.json` and create your assets (SVG, GIF, APNG, WebP, PNG, JPG, or JPEG) 3. Restart Clawd or open `Settings…` → `Theme` → select your theme **Minimum viable theme:** 1 SVG (idle with eye tracking) + 7 GIF/APNG files (thinking, working, error, happy, notification, sleeping, waking). Eye tracking can be disabled to use any format for all states. Validate your theme before distributing: ```bash node scripts/validate-theme.js path/to/your-theme ``` Theme cards in `Settings…` → `Theme` now expose capability badges such as `Tracked idle`, `Static theme`, `Mini`, `Direct sleep`, and `No reactions`, so users can tell what a theme supports before switching. See [docs/guides/guide-theme-creation.md](docs/guides/guide-theme-creation.md) for the full creation guide with tiered paths (beginner → advanced), `theme.json` field reference, and asset guidelines. > Third-party SVG files are automatically sanitized for security. ### Roadmap Some things we'd like to explore in the future: - Codex terminal focus via process tree lookup from `codex.exe` PID - Auto-registration of Copilot CLI hooks (like we do for Claude Code) - Theme registry and in-app download - Hook uninstall script for clean app removal ## Contributing Clawd on Desk is a community-driven project. Bug reports, feature ideas, and pull requests are all welcome — open an [issue](https://github.com/rullerzhou-afk/clawd-on-desk/issues) to discuss or submit a PR directly. ### Maintainers

_{@rullerzhou-afk
鹿鹿 · creator}

_{@YOIMIYA66
maintainer}

### Contributors Thanks to everyone who has helped make Clawd better:

Show all 47 contributors

_{PixelCookie-zyf}	_yujiachen-y	_AooooooZzzz	_purefkh	_{Tobeabellwether}	_Jasonhonghh	_crashchen
_hongbigtou	_InTimmyDate	_NeizhiTouhu	_{xu3stones-cmd}	_androidZzT	_Ye-0413	_WanfengzzZ
_TaoXieSZ	_ssly	_stickycandy	_Rladmsrl	_YOIMIYA66	_Kevin7Qi	_{sefuzhou770801-hub}
_Tonic-Jin	_seoki180	_{sophie-haynes}	_PeterShanxin	_{CHIANGANGSTER}	_{JaeHyeon-KAIST}	_hhhzxyhhh
_TVpoet	_zeus6768	_anhtrinh919	_tomaioo	_v-avuso	_livlign	_tongguang2
_Ziy1-Tan	_{tatsuyanakanogaroinc}	_yeonhub	_joshua-wu	_nmsn	_sunnysonx	_YuChenYunn
_jhseo-b	_Hwasowl	_{XiangZheng2002}	_keiyo118	_pan93412

## Acknowledgments - Clawd pixel art reference from [clawd-tank](https://github.com/marciogranzotto/clawd-tank) by [@marciogranzotto](https://github.com/marciogranzotto) - Shared on [LINUX DO](https://linux.do/) community ## License Source code is licensed under the [GNU Affero General Public License v3.0](LICENSE) (AGPL-3.0). **Artwork and bundled theme assets (including `assets/` and `themes/*/assets/`) are NOT covered by AGPL-3.0.** All rights reserved by their respective copyright holders. See [assets/LICENSE](assets/LICENSE) and the notices below for details. - **Clawd** character is the property of [Anthropic](https://www.anthropic.com). This is an unofficial fan project, not affiliated with or endorsed by Anthropic. - **Calico cat (三花猫)** artwork by 鹿鹿 ([@rullerzhou-afk](https://github.com/rullerzhou-afk)). All rights reserved. - **Cloudling (云宝)** artwork by 鹿鹿 ([@rullerzhou-afk](https://github.com/rullerzhou-afk)). All rights reserved. Cloudling's visual direction includes an homage to the OpenAI Codex logo; Codex/OpenAI marks remain the property of OpenAI, and this project is not affiliated with or endorsed by OpenAI. - **Third-party contributions**: copyright retained by respective artists. **No cryptocurrency.** This project has no token, coin, NFT, or airdrop, and is not affiliated with any cryptocurrency project.