clawd-conduit

Wire a desktop pet into what your Claude Code session is actually doing — all 15 hook events.

中文 · macOS · MIT

What this is

Clawd on Desk is a desktop pet that watches AI coding agents. It ships with Claude Code integration and works out of the box.

This repo is a complete wiring layer on top of it: all 15 Claude Code lifecycle hook events, plus a notification script, an idempotent install/uninstall toolchain, and the parameter trade-offs I settled on after three months of daily use.

The difference is granularity. With fewer events the pet roughly knows whether you're busy or idle. With all 15 it can tell you're running a tool, that a tool just failed, that subagents are running in parallel, that context is being compacted — or that it's blocked on a confirmation waiting for you.

That last one is the whole point.

The problem it actually solves

During long runs you leave the terminal — docs, messages, coffee. You come back and find it stopped three minutes ago waiting for you to click "allow."

This config cuts those three minutes to zero:

• Permission requests surface as a desktop card: Cmd+Shift+Y to allow, Cmd+Shift+N to deny — no window switching
• The card never auto-dismisses (permissionBubbleAutoCloseSeconds: 0). Auto-dismiss is the worst default here: you think you denied it, but it just timed out and fell back to the terminal prompt
• Dock flash + sound on completion, so you catch it from another app
• Tool failures change the pet's state immediately — no scrolling back to find which step blew up

How it works

Claude Code fires hooks at key points in a session's lifecycle. This config forwards 14 of them as command hooks to Clawd's bundled clawd-hook.js, and routes one more — the permission request — as an http hook straight to Clawd's local port.

Claude Code                          Clawd on Desk
    │
    ├─ SessionStart ─┐
    ├─ PreToolUse  ──┤  command hook
    ├─ Stop        ──┼─→ clawd-hook.js ──→ POST 127.0.0.1:23333/state ──→ pet changes state
    ├─ … (14 total) ─┘        (async, 5s timeout, never blocks the session)
    │
    └─ PermissionRequest ─→ HTTP hook ──→ POST 127.0.0.1:23333/permission
                                              (blocking, 600s timeout)
                                                    │
                                          card pops ┴─→ you click Allow / Deny
                                                         └─→ decision returns, session continues

The two channels differ in whether they wait for you. State events are one-way broadcasts — fire and forget. A permission request has to stop and wait for a human decision, which is why it is the only blocking one.

Events and pet states

Taken from Clawd's clawd-hook.js (EVENT_TO_STATE) — not guesswork:

One detail worth knowing: on some builds Claude Code reports subagent launches only as PreToolUse(Task) without a native SubagentStart. Clawd handles this by switching to juggling on the Task / Agent tool name — so parallel work never goes unreported.

Why the template uses absolute paths

"command": "\"/opt/homebrew/bin/node\" \"/Applications/Clawd on Desk.app/…/clawd-hook.js\" Stop"

Hooks run in a non-login shell, where PATH may not include Homebrew. A bare node becomes command-not-found — and because these are async: true, you never see the error. The symptom is just a pet that quietly stops moving. install.sh detects and fills both paths for you.

The path contains a space (Clawd on Desk.app), so every segment must be quoted.

Quick start

# 1. Install Clawd on Desk itself (not bundled or redistributed here)
#    https://github.com/rullerzhou-afk/clawd-on-desk/releases

# 2. Apply this config
git clone https://github.com/ssssssanjiu/clawd-conduit.git
cd clawd-conduit
bash install.sh

Start a new Claude Code session to pick it up.

What install.sh does

1. Locate Clawd — checks /Applications, then ~/Applications, then falls back to mdfind on bundle id com.clawd.on-desk. Fails loudly with a download link if it can't find it.
2. Locate node — checks /opt/homebrew/bin/node, /usr/local/bin/node, then command -v node.
3. Back up — copies your settings.json to settings.json.bak.<timestamp>.
4. Merge hook config — fills the placeholder template with real paths. Preserves your other hooks per event, replacing only entries this repo wrote itself.
5. Install the notification script — copies it to ~/.claude/hooks/ and attaches it to Notification (skippable).
6. Validate — runs python3 -c "json.load(...)" to confirm the JSON it wrote is still parseable.

Safe to re-run. A second run replaces rather than appends; the occurrence count of clawd-hook.js stays at exactly 14.

Verify it took

# 1. Are all 15 events wired?
python3 -c "import json;h=json.load(open('$HOME/.claude/settings.json'))['hooks'];\
print(len([k for k,v in h.items() if 'clawd' in json.dumps(v).lower() or '23333' in json.dumps(v)]),'events')"

# 2. Is Clawd's local service listening?
lsof -nP -iTCP:23333 -sTCP:LISTEN

# 3. Does the hook script path actually exist?
ls -l "/Applications/Clawd on Desk.app/Contents/Resources/app.asar.unpacked/hooks/clawd-hook.js"

The first should print 15 events; the second should show a Clawd on Desk process. Once both check out, start a session and send any message — the pet should go from idle to thinking.

Troubleshooting

Check three things, in order:

1. Wrong node path. By far the most common cause. Hooks are async, so failures are completely silent. Run one by hand to see the error:

   echo '{"session_id":"t","hook_event_name":"Stop"}' | \
     /opt/homebrew/bin/node "/Applications/Clawd on Desk.app/Contents/Resources/app.asar.unpacked/hooks/clawd-hook.js" Stop
   

2. Clawd isn't running. pgrep -f "Clawd on Desk" should print a PID.
3. Config wasn't reloaded. Hooks are read at session start — you need a new session; the current one won't hot-reload.

• permissionBubblesEnabled must be true in Clawd's settings
• hideBubbles must be false
• Port 23333 must be listening (check #2 above)
• If you run Claude Code with --dangerously-skip-permissions, or the action is already allowlisted, no permission request is generated at all — that's not a bug

You probably set notificationBubbleAutoCloseSeconds to 0.

The two bubble kinds treat 0 in opposite ways. For permission bubbles 0 means "never auto-clos