ClaudeMap

clawd-conduit

Wire all 15 Claude Code hook events into the Clawd on Desk desktop pet — and turn permission requests into a blocking desktop card.

Plugins & Agentshooksdesktopnotificationsclaude-codemacos
Visit projectssssssanjiu/clawd-conduit

clawd-conduit is a wiring layer over the Clawd on Desk desktop pet that gives a Claude Code session a visible body. It forwards 14 lifecycle events as async command hooks (5-second timeout, never blocks the session) to Clawd's bundled clawd-hook.js, and routes the one event that matters most — PermissionRequest — as a blocking HTTP hook straight to Clawd's local port with a 600-second wait: the permission lands as a desktop card, Cmd+Shift+Y allows, Cmd+Shift+N denies, and the card never auto-dismisses, so the classic "it stopped three minutes ago waiting for me to click allow" gap goes to zero. Every event maps to a pet state read from Clawd's own EVENT_TO_STATE table: subagents juggle, context compaction sweeps, tool failures smoke. The idempotent install.sh backs up settings.json with a timestamp, merges hooks per event while preserving yours, fills absolute node and app paths (hooks run in non-login shells where bare node silently fails), validates the JSON it wrote, and is safe to re-run — the clawd-hook.js occurrence count stays at exactly 14.

What it does

  • All 15 hook events wired: 14 as async command hooks with a 5-second timeout, plus PermissionRequest as the only blocking channel (HTTP, 600-second wait)
  • Permission cards on the desktop: Cmd+Shift+Y / Cmd+Shift+N without window switching, auto-close disabled (permissionBubbleAutoCloseSeconds: 0), destructive-action warnings on rm -rf
  • Event-to-state mapping taken from Clawd's own EVENT_TO_STATE — SubagentStart juggles, PreCompact sweeps, PostToolUseFailure errors, SessionEnd sleeps
  • Idempotent toolchain: timestamped settings.json backup, per-event merge that preserves your hooks, absolute-path resolution for non-login shells, JSON validation, and a re-run that replaces rather than appends

When to use it

macOS users who run long Claude Code sessions and walk away — the pet tells you at a glance whether the session is working, blocked on a confirmation, or failed, and the permission card removes the round-trip back to the terminal.

Getting started

# 1. install Clawd on Desk itself (not bundled):
#    https://github.com/rullerzhou-afk/clawd-on-desk/releases
git clone https://github.com/ssssssanjiu/clawd-conduit.git
cd clawd-conduit && bash install.sh

# 2. verify:
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')"
lsof -nP -iTCP:23333 -sTCP:LISTEN

# 3. start a NEW Claude Code session — hooks load at session start

Things to know

macOS only. Requires the separate Clawd on Desk app — the pet and its local service on port 23333 are the whole display layer. Async hooks fail silently by design: if the pet does nothing, run one hook by hand to see the error, check Clawd is running (pgrep -f "Clawd on Desk"), and start a new session since hooks never hot-reload. No permission cards appear when running with --dangerously-skip-permissions or when the action is already allowlisted — that is Claude Code's behavior, not a bug. The parameter trade-offs (blocking permission channel, no auto-dismiss) reflect three months of the author's daily use. MIT.

Repository

ssssssanjiu/clawd-conduit

Charted

Related on the map

  • CometixCode

    Plugin / Agent

    An unofficial Rust 1:1 reimplementation of the Claude Code terminal UI, ported file-for-file onto an iocraft TUI framework.

    • terminal-ui
    • rust
    • reimplementation
    • unofficial
    View

  • Abide

    Plugin / Agent

    Hook-level enforcement for the natural-language rules in AGENTS.md and CLAUDE.md — every edit is judged and violations are repaired in the same turn.

    • hooks
    • code-review
    • rules
    • agents-md
    View

  • fast-jev-compaction

    Plugin / Agent

    A Claude Code plugin that replaces the lossy compaction summary with Jev-scored pruning: stale tool calls are dropped, and everything kept stays verbatim.

    • plugin
    • context-management
    • compaction
    • function-hooks
    View