hey-clawd

English · 简体中文

A macOS menu-bar desktop pet — Clawd reacts in real time to what your AI coding assistant is doing. It integrates with Claude Code, Codex CLI, Cursor, Gemini CLI, GitHub Copilot CLI, CodeBuddy and Pi, and plays different animations for idle / thinking / working / error / sleep states. For Claude Code and CodeBuddy it can surface tool-use permission prompts as floating bubbles so you never have to return to the terminal just to click "allow"; Codex CLI permission review is available as an experimental opt-in.

Highlights

• Reacts to 7 AI coding tools — Claude Code, CodeBuddy, Codex CLI, Cursor, Gemini CLI and Copilot CLI via hooks; Pi via extension.
• Permission bubbles — approve or deny tool use for Claude Code / CodeBuddy without leaving your editor; Codex CLI supports experimental single Allow / Deny review behind an explicit toggle.
• Custom Core Animation SVG pipeline — no WebView. 50+ hand-drawn states on a 15×16 pixel grid, cached via LRU.
• Lightweight & native — Swift 6 + AppKit/Core Animation. No WebView, no embedded JS runtime. Low CPU and memory footprint.
• Menu-bar only (LSUIElement) with mini edge-hugging mode, eye tracking that follows your cursor, and a Do-Not-Disturb toggle.
• Auto-updating via Sparkle (EdDSA-signed appcast).
• Single external dependency: Sparkle. Everything else is Swift 6 + stdlib.

Requirements

• macOS 12 (Monterey) or newer
• Node.js (for bundled installers to register hooks/extensions into Claude Code / Cursor / Gemini / CodeBuddy / Codex CLI / Pi on first launch)

Install

Download the release

Grab the latest .dmg from GitHub Releases, drag hey-clawd.app into /Applications, and launch. The app lives in the menu bar — right-click the Clawd icon to open the tray menu.

If macOS Gatekeeper blocks launch, first try right-click → Open once. If you see messages like “app is damaged”, “Apple could not verify”, or the app simply refuses to open, remove the quarantine flag manually:

xattr -dr com.apple.quarantine /Applications/hey-clawd.app

Then launch the app again.

On first launch it starts a local HTTP server on 127.0.0.1:23333 (falls back to 23334–23337) and runs the bundled installers to register hooks/extensions into any detected AI tools. Tools that aren't installed are skipped. You can re-run registration anytime from the tray menu → Hooks → Register.

Codex CLI state hooks are registered by default, but Codex permission review is off by default so native terminal approval stays intact. To opt in, enable Hooks → Experiments → Codex Permission Review; turning it off removes only the Codex PermissionRequest hook and keeps state sync. Codex CLI may also require an extra /hooks review inside Codex before newly registered command hooks are trusted and allowed to run.

Build from source

# Swift Package Manager (debug)
swift build
.build/debug/hey-clawd

# Release build
swift build -c release

# Xcode (matches CI)
xcodebuild -project hey-clawd.xcodeproj -scheme hey-clawd -configuration Release archive

Supported integrations

Tool	Method	Direction	Permission bubble	Terminal focus
Claude Code	hook	bidirectional	✅	✅
CodeBuddy	hook	bidirectional	✅	✅
Gemini CLI	hook	one-way	—	✅
Cursor	hook	one-way	—	✅
Copilot CLI	hook	one-way	—	✅
Codex CLI	hook	bidirectional	experimental single Allow/Deny	✅
Pi	extension	one-way	—	✅

See docs/integrations/platform-comparison.md for the full event-coverage matrix and per-tool deep dives in docs/integrations/.

How it works

IDE/CLI hooks / Pi extension              →  HTTP POST /state       →  HTTPServer  →  StateMachine  →  PetView (Core Animation)
Permission hooks (optional for Codex CLI) →  HTTP POST /permission  →  HTTPServer  →  BubbleStack   →  allow/deny

• StateMachine — priority-based aggregator (priority 0–8) across concurrent sessions. Higher-priority states override lower ones; one-shot states (attention, error, notification) play once then revert.
• SVG pipeline — SVGParser → SVGDocument (LRU cache) → CALayerRenderer → CAAnimationBuilder (CSS keyframes → Core Animation). See docs/rendering-system.md.
• Integration bridge (hooks/) — CommonJS hook handlers and installers (clawd-hook.js, cursor-hook.js, gemini-hook.js, codebuddy-hook.js, copilot-hook.js, codex-hook.js, plus their *-install.js scripts), plus the Pi extension/installer pair (pi-extension.ts, pi-install.js). Each integration ultimately maps tool lifecycle events to pet states and POSTs to the local HTTP server. Port discovery: ~/.clawd/runtime.json first, then scans 23333–23337.
• HTTP endpoints — /state, /permission, /status, /quit, plus /debug/svg and /debug/reset for development.

State gallery

A peek at the raw SVG states. These are CSS-animated and rendered natively by the Core Animation pipeline at runtime — what you see in GitHub is the exact same source file the app consumes.

Idle	Typing	Thinking	Wizard	Happy
idle-living	working-typing	working-thinking	working-wizard	happy

Smoking	Reading	Music	Dozing	Sleeping
idle-smoking	idle-reading	idle-music	idle-doze	sleeping

Full catalog of 50+ states: docs/svg-catalog.md.

Develop

# Swift test target (SVG parsing/rendering, HTTP server, hook installer, state machine)
swift test

# Permission-bubble integration tests (hits a running app)
./test-bubble.sh all         # or: single | stack | passthrough | disconnect | dnd

# SVG animation visual smoke test (hits /debug/svg on a running app)
./test-animations.sh

# Hook-side Node tests
cd hooks && node test/index.js

Further docs:

• docs/svg-catalog.md — every PetState → SVG mapping.
• docs/svg-animation-spec.md — SVG animation, pixel-grid, and palette spec.

License

MIT — retains the original copyright from clawd-on-desk.

Acknowledgements

• Form and architecture derived from @rullerzhou-afk's clawd-on-desk.
• Some art direction and animation inspiration was also referenced from @marciogranzotto's clawd-tank. Thank you for the lovely Clawd worldbuilding and pixel-art ideas.
• Shared with the LINUX DO community.