@agent-mokugyo/hooks

Auto-knock the mokugyo desk companion when Claude Code / Codex finishes meaningful work.

One command installs a Stop hook into your Claude Code / Codex settings. When the Agent completes a task that involved real tool use (file edits, code execution, etc.), the hook automatically sends a knock to the Mokugyo backend — driving the physical desk-cat device or simulator.

Pure chat responses (no tool use) are silently ignored.

Install

npx @agent-mokugyo/hooks install

This injects a Stop hook entry into ~/.claude/settings.json.

Uninstall

npx @agent-mokugyo/hooks uninstall

Configuration

Set these environment variables (all optional):

| Variable | Default | Description | |----------|---------|-------------| | MOKUGYO_BACKEND_URL | http://localhost:8080 | Mokugyo backend HTTP address | | MOKUGYO_DEVICE_ID | desk-cat-001 | Target device ID | | MOKUGYO_TOKEN | — | Bearer token if backend requires auth |

How It Works

1. Claude Code finishes responding → fires the Stop hook
2. on-stop.mjs reads the hook context (stdin JSON with transcript_path)
3. Parses the JSONL transcript to find the last assistant turn
4. Counts tool_use blocks — if > 0, the Agent did meaningful work
5. POSTs a knock to the backend (count scales with tool uses, max 8)
6. If backend is unreachable, silently exits (never blocks Claude)

Knock Behavior

| Tool uses | Count | Pattern | Intensity | |-----------|-------|---------|-----------| | 1–2 | 1–2 | single | normal | | 3–4 | 3–4 | short-short-long | normal | | 5–8 | 5–8 | short-short-long | strong |

Requirements

• Node.js 18+ (for native fetch)
• Claude Code or Codex (provides the hooks infrastructure)
• Mokugyo backend running at MOKUGYO_BACKEND_URL (see agent-mokugyo for setup)

License

MIT