Clawd on Desk

中文版

A desktop pet that reacts to your AI coding agent sessions in real-time. Clawd lives on your screen — thinking when you prompt, typing when tools run, juggling subagents, reviewing permissions, celebrating when tasks complete, and sleeping when you're away.

Supports Windows 11, macOS, and Ubuntu/Linux. Requires Node.js. Works with Claude Code, Codex CLI, Copilot CLI, Gemini CLI, Cursor Agent, Kiro CLI, and opencode.

Features

Multi-Agent Support

• Claude Code — full integration via command hooks + HTTP permission hooks
• Codex CLI — automatic JSONL log polling (~/.codex/sessions/), no configuration needed
• 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 in ~/.cursor/hooks.json (registered automatically when Clawd starts, or run npm run install:cursor-hooks)
• 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 have been verified on macOS.
• opencode — plugin integration 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
• 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, juggling, conducting, error, happy, notification, sweeping, carrying, sleeping
• 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 requests tool permissions, Clawd pops a floating bubble card instead of waiting in the terminal
• Allow / Deny / Suggestions — one-click approve, reject, or apply permission rules (e.g. "Always allow Read")
• 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

Session Intelligence

• Multi-session tracking — sessions across all agents resolve to the highest-priority state
• Subagent awareness — juggling for 1 subagent, conducting for 2+
• Terminal focus — right-click Clawd → Sessions menu to jump to a specific session's terminal window; notification/attention states auto-focus the relevant terminal
• Process liveness detection — detects crashed/exited agent processes (Claude Code, Codex, Copilot) and cleans up orphan sessions
• Startup recovery — if Clawd restarts while any agent is 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 — opencode falls back to its built-in TUI prompt, and Claude Code will handle permissions automatically
• 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 and Chinese 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

State Mapping

Events from all agents (Claude Code hooks, Codex JSONL, Copilot hooks) map to the same animation states:

Agent Event	Clawd State	Animation
Idle (no activity)	idle	Eye-tracking follow
Idle (random)	idle	Reading a book
Idle (random)	idle	Debugger patrol
UserPromptSubmit	thinking	Thought bubble
PreToolUse / PostToolUse	working (typing)	Typing
PreToolUse (3+ sessions)	working (building)	Building
SubagentStart (1)	juggling	Juggling
SubagentStart (2+)	conducting	Conducting
PostToolUseFailure / StopFailure	error	ERROR + smoke
Stop / PostCompact	attention	Happy bounce
PermissionRequest / Notification	notification	Alert jump
PreCompact	sweeping	Broom sweep
WorktreeCreate	carrying	Carrying box
60s no events	sleeping	Sleep sequence

Mini Mode

Drag Clawd to the right screen edge (or right-click → "Mini Mode") to enter mini mode. Clawd hides behind the screen edge with half-body visible, peeking out when you hover.

Trigger	Mini Reaction
Default	Breathing + blinking + occasional arm wobble + eye tracking
Hover	Peek out + wave (slides 25px into screen)
Notification / PermissionRequest	Exclamation mark pop + >< squint eyes
Stop / PostCompact	Flower + ^^ happy eyes + sparkles
Click during peek	Exit mini mode (parabolic jump back)

Click Reactions

Easter eggs — try double-clicking, rapid 4-clicks, or poking Clawd repeatedly to discover hidden reactions.

Quick Start

# 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

Agent Setup

Claude Code — works out of the box. Hooks are auto-registered on launch. Versioned hooks (PreCompact, PostCompact, StopFailure) are registered only when Clawd can positively detect a compatible Claude Code version; if detection fails (common for packaged macOS launches), Clawd falls back to core hooks and removes stale incompatible versioned hooks automatically.

Codex CLI — works out of the box. Clawd polls ~/.codex/sessions/ for JSONL logs automatically.

Copilot CLI — requires manual hook setup. See docs/copilot-setup.md for instructions.

Kiro CLI — run npm run install:kiro-hooks if you want hooks registered before launching Clawd. Kiro's built-in kiro_default agent is not backed by an editable JSON file, so Clawd creates a custom clawd agent and re-syncs it from the latest kiro_default each time Clawd starts, then appends hooks. Use kiro-cli --agent clawd for a new chat, or /agent swap clawd inside an existing Kiro session, when you want hooks enabled. On macOS, state-driven animations have been verified; native terminal permission prompts such as t / y / n still need to be answered in the terminal.

Remote SSH (Claude Code & Codex CLI)

Clawd can sense AI agent activity on remote servers via SSH reverse port forwarding. Hook events and permission requests travel through the SSH tunnel back to your local Clawd — no code changes needed on the Clawd side.

One-click deploy:

bash scripts/remote-deploy.sh user@remote-host

This copies hook files to the remote server, registers Claude Code hooks in remote mode, and prints SSH configuration instructions.

SSH configuration (add to your local ~/.ssh/config):

Host my-server
    HostName remote-host
    User user
    RemoteForward 127.0.0.1:23333 127.0.0.1:23333
    ServerAliveInterval 30
    ServerAliveCountMax 3

How it works:

• Claude Code — command hooks on the remote server POST state changes to localhost:23333, which the SSH tunnel forwards back to your local Clawd. Permission bubbles work too — the HTTP round-trip goes through the tunnel.
• Codex CLI — a standalone log monitor (codex-remote-monitor.js) polls JSONL files on the remote server and POSTs state changes through the same tunnel. Start it on the remote: node ~/.claude/hooks/codex-remote-monitor.js --port 23333

Remote hooks run in CLAWD_REMOTE mode which skips PID collection (remote PIDs are meaningless locally). Terminal focus is not available for remote sessions.

Thanks to @Magic-Bytes for the original SSH tunneling idea (#9).

macOS Notes

• From source (npm start): works out of the box on Intel and Apple Silicon.
• DMG installer: the app is not signed with an Apple Developer certificate, so macOS Gatekeeper will block it. To open:
  • Right-click the app → Open → click Open in the dialog, or
  • Run xattr -cr /Applications/Clawd\ on\ Desk.app in Terminal.

Linux Notes

• From source (npm start): --no-sandbox is passed automatically to work around chrome-sandbox SUID requirements in dev mode.
• Packages: AppImage and .deb are available from GitHub Releases. After deb install, the app icon appears in GNOME's app menu.
• Terminal focus: uses wmctrl or xdotool (whichever is available). Install one for session terminal jumping to work: sudo apt install wmctrl or sudo apt install xdotool.
• Auto-update: when running from a cloned repo, "Check for Updates" performs git pull + npm install (if dependencies changed) and restarts the app automatically.

Known Limitations

Limitation	Details
Codex CLI: no terminal focus	Codex sessions use JSONL log polling which doesn't carry terminal PID info. Clicking Clawd won't jump to the Codex terminal. Claude Code and Copilot CLI work fine.
Codex CLI: Windows hooks disabled	Codex hardcodes hooks off on Windows, so we poll log files instead. This means ~1.5s latency vs near-instant for hook-based agents.
Copilot CLI: manual hook setup	Copilot hooks require manually creating ~/.copilot/hooks/hooks.json. Claude Code and Codex work out of the box.
Copilot CLI: no permission bubble	Copilot's preToolUse hook only supports deny, not the full allow/deny flow. Permission bubbles only work with Claude Code.
Gemini CLI: no working state	Gemini's session JSON only records completed messages, not in-progress tool execution. The pet jumps from thinking straight to happy/error — no typing animation during work.
Gemini CLI: no permission bubble	Gemini handles tool approval inside the terminal. File polling can't intercept or display approval requests.
Gemini CLI: no terminal focus	Session JSON doesn't carry terminal PID info, same limitation as Codex.
Gemini CLI: polling latency	~1.5s poll interval + 4s defer window for batching tool completion signals. Noticeably slower than hook-based agents.
Cursor Agent: no permission bubble	Cursor handles permissions via stdout JSON in the hook, not HTTP blocking — Clawd can't intercept the approval flow.
Cursor Agent: startup recovery	No process detection on startup (matching the editor PID would false-trigger on any Cursor instance). Clawd stays idle until the first hook event fires.
Kiro CLI: no session tracking	Kiro CLI stdin JSON has no session_id — all Kiro sessions are merged into a single tracked session.
Kiro CLI: no SessionEnd	Kiro CLI has no session end event, so Clawd can't detect when a Kiro session ends.
Kiro CLI: no subagent detection	Kiro CLI has no subagent events, so juggling/conducting animations won't trigger.
Kiro CLI: terminal permission prompts stay in terminal	Kiro state hooks are verified on macOS, but when Kiro shows native terminal permission prompts such as t / y / n, those still need to be handled in the terminal. Clawd does not currently replace that flow.
opencode: subtask menu clutter	When opencode delegates to parallel subagents via the task tool, the subagent sessions briefly appear in the Sessions submenu while they run (5-8 seconds), then self-clean. Cosmetic only — the building animation fires correctly.
opencode: terminal focus limited to spawning terminal	The plugin runs in-process with opencode, so source_pid points to the terminal that launched opencode. If you use opencode attach from a different window, terminal focus jumps to the original launcher.
macOS/Linux packaged auto-update	DMG/AppImage/deb installs cannot auto-update — use git clone + npm start for auto-update via git pull, or download new versions manually from GitHub Releases.
No test framework for Electron	Unit tests cover agents and log polling, but the Electron main process (state machine, windows, tray) has no automated tests.

Custom Themes

Clawd supports custom themes — replace the default crab with your own character and animations.

Quick start:

1. Copy themes/template/ to your themes directory:
   • Windows: %APPDATA%/clawd-on-desk/themes/my-theme/
   • macOS: ~/Library/Application Support/clawd-on-desk/themes/my-theme/
   • Linux: ~/.config/clawd-on-desk/themes/my-theme/
2. Edit theme.json and create your assets (SVG, GIF, APNG, or WebP)
3. Right-click Clawd → 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:

node scripts/validate-theme.js path/to/your-theme

See docs/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 to discuss or submit a PR directly.

Contributors

Thanks to everyone who has helped make Clawd better:

PixelCookie-zyf	yujiachen-y	AooooooZzzz	purefkh	Tobeabellwether
Jasonhonghh	crashchen	hongbigtou	InTimmyDate	NeizhiTouhu
xu3stones-cmd	androidZzT	Ye-0413	WanfengzzZ	TaoXieSZ
ssly

Acknowledgments

• Clawd pixel art reference from clawd-tank by @marciogranzotto
• Shared on LINUX DO community

License

Source code is licensed under the MIT License.

Artwork (assets/) is NOT covered by MIT. All rights reserved by their respective copyright holders. See assets/LICENSE for details.

• Clawd character is the property of Anthropic. This is an unofficial fan project, not affiliated with or endorsed by Anthropic.
• Calico cat (三花猫) artwork by 鹿鹿 (@rullerzhou-afk). All rights reserved.
• Third-party contributions: copyright retained by respective artists.