pocket-claudes

Pocket Claudes

What it is

Claude Code plugin. Pairs with the PocketClaudes Unity 6 desktop overlay game (separate download). Each running Claude Code session → one NPC walking on the user's desktop. Hooks here forward event metadata over loopback HTTP; the game renders the NPCs and animates them per event.

The plugin alone does nothing visible — the game is the renderer. The game alone does nothing — the plugin is its only data source.

How it works

• hooks/hooks.json registers 14 hook events. Each event runs one command: bash scripts/hook-event.sh || powershell ... scripts/hook-event.ps1 — bash first (macOS/Linux), PowerShell fallback (Windows). No external runtime dep.
• The script reads hook JSON from stdin, extracts a fixed metadata set, walks the parent-process chain for hostPid, builds a flat versioned IpcCommand, and POSTs to http://127.0.0.1:1604/.
• If the POST fails the event is dropped. The plugin never launches the game — the user is responsible for starting it. So events fired before the game is running (or after a manual close) silently no-op.
• Game enforces single-instance via a named Mutex; if a second process starts it exits immediately.
• Game's dispatcher is self-healing: unknown session_id lazily spawns the NPC; unknown agent_id lazily spawns a mini NPC; duplicate SessionStart reuses. So SessionStart is an optimization, never a precondition — the first event delivered to a running game spawns the NPC regardless of type.

Privacy

Hook forwards only: eventName, sessionId, agentId, agentType, toolName, toolUseId, model, cwd, hostPid. Never prompt text, tool inputs/results, file contents, command output, Claude responses, or transcript path. Game listens on 127.0.0.1:1604 only — no outbound network. Both scripts are <100 lines; audit them directly.

Troubleshooting

• No NPC on first session. The game isn't running. Launch the PocketClaudes executable, then trigger any hook event (e.g. send a prompt) — the next event spawns the NPC via the self-healing dispatcher.
• Game crashes immediately with a dialog. Port 1604 is in use (fixed, no discovery). Kill the conflicting process; check netstat -ano | findstr :1604 (Windows) or lsof -i :1604 (mac/Linux).
• NPC stuck in wrong state. Hook event missed or out of order. Next event self-corrects via the idempotent dispatcher; no manual fix.
• Clicking NPC focuses the wrong window. hostPid resolution failed. Linux needs xdotool; macOS uses osascript; Windows uses Win32_Process. Install missing tool and restart the session.