A desktop pet that reacts to your Claude Code sessions in real-time — thinking, typing, juggling, sleeping, and more.
# Add to your Claude Code skills
git clone https://github.com/rullerzhou-afk/clawd-on-deskA 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, and Cursor Agent.
~/.codex/sessions/), no configuration needed~/.copilot/hooks/hooks.json~/.gemini/settings.json (registered automatically when Clawd starts, or run npm run install:gemini-hooks)~/.cursor/hooks.json (registered automatically when Clawd starts, or run npm run install:cursor-hooks)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 | |
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) | |
Easter eggs — try double-clicking, rapid 4-clicks, or poking Clawd repeatedly to discover hidden reactions.
# 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 — 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.
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:
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-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 23333Remote 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).
npm start): works out of the box on Intel and Apple Silicon.xattr -cr /Applications/Clawd\ on\ Desk.app in Terminal.npm start): --no-sandbox is passed automatically to work around chrome-sandbox SUID requirements in dev mode..deb are available from GitHub Releases. After deb install, the app icon appears in GNOME's app menu.wmctrl or xdotool (whichever is available). Install one for session terminal jumping to work: sudo apt install wmctrl or `sudo apt install xdotooNo comments yet. Be the first to share your thoughts!