carmoji 0.1.0

package/README.md

@@ -0,0 +1,120 @@
+# CarMoji Bridge
+
+Forwards coding events from **Claude Code** and **Codex** on your computer
+to the CarMoji pet on your phone, over a WebSocket on the same Wi-Fi.
+The pet wakes up when a session starts, "types" while the agent edits,
+gets nervous while tests run, celebrates finished turns, and pleads with
+big puppy eyes when the agent is waiting for your approval.
+
+## Setup (once)
+
+1. On the phone: open CarMoji, tap the laptop icon (top-left), turn on
+   **Listen on this Wi-Fi**, and note the 4-digit pairing code.
+2. On your computer (Node.js ≥ 18):
+
+   ```sh
+   npx carmoji pair <code>
+   ```
+
+   The phone is discovered automatically via Bonjour — no IP addresses.
+   Pairing sends a test event, so the pet celebrates when it works.
+
+   With several phones (or a simulator) on the network, `pair` lists what
+   it found and asks which one you mean. You can also skip discovery and
+   pair by the address shown on the Code Buddy sheet:
+
+   ```sh
+   npx carmoji pair <code> 192.168.1.23:8737
+   ```
+
+   (Working from a clone of this repo, `cd bridge && npm install &&
+   node carmoji.js …` does the same thing.)
+
+   `npx carmoji discover` lists every CarMoji it can see without
+   pairing — handy for checking connectivity. On macOS discovery goes
+   through the system's `dns-sd`, which handles Macs full of VPN tunnels
+   and virtual interfaces; other platforms use a JS mDNS fallback.
+
+## Claude Code
+
+Coding in *this* repo works out of the box — the hooks ship in
+[.claude/settings.json](../.claude/settings.json). To get reactions in
+every project, print the snippet and merge it into `~/.claude/settings.json`:
+
+```sh
+npx carmoji claude-config
+```
+
+## Codex
+
+```sh
+npx carmoji codex-config
+```
+
+prints the `notify = [...]` line for `~/.codex/config.toml`. Codex's notify
+surface only reports completed turns, so the pet celebrates finished work
+but doesn't see individual edits (tail `~/.codex/sessions/` is a possible
+future upgrade — see [docs/ROADMAP.md](../docs/ROADMAP.md)).
+
+## Try it without a coding agent
+
+```sh
+npx carmoji test start       # wakes up, excited
+npx carmoji test edit        # focused typing face
+npx carmoji test run         # nervous side-eye
+npx carmoji test permission  # pleading + floating "?"
+npx carmoji test done        # celebration with hearts
+npx carmoji test error       # dizzy collapse
+npx carmoji test end         # contented sigh
+```
+
+## Multiple agents & token speed
+
+- Every message carries the Claude Code `session_id` (or Codex conversation
+  id), so several agents can run at once. The pet plays the latest event,
+  but if one agent is still blocked waiting for your approval, it returns
+  to the pleading face after another agent's reaction — and stops pleading
+  as soon as the blocked session moves again.
+- The bridge counts each session's cumulative output tokens by tailing the
+  transcript incrementally (per-session byte offsets in
+  `~/.config/carmoji/sessions/`). While in buddy mode, the dashboard's
+  speed readout switches from km/h to **tok/s** — combined across all
+  agents — with the active agent count below it.
+
+## What the phone shows
+
+In buddy mode the dashboard swaps the car for a little robot sprite that
+scans while agents work, goes wide-eyed with a "?" when one waits for your
+approval, and dozes when everyone's idle — with a dot per connected agent
+and the active project's name underneath. The laptop button gets a green
+dot while agents are live, and GPS pauses to save battery. Prompt snippets
+and permission messages (first ~140 chars) are sent to the phone as brief
+toasts; they stay on your LAN and are only accepted by the paired device.
+
+## Answer permissions from the phone (Claude Code, opt-in)
+
+```sh
+npx carmoji gate-config
+```
+
+prints a `PreToolUse` hook snippet with a tool matcher (e.g. `Bash`). With
+it installed, whenever Claude wants to run a matched tool the phone chimes
+(a doorbell sound used by nothing else), shows big pleading eyes, and pops
+an **Allow / Deny** card with the command text — your tap settles the
+permission on the computer via the hook's official decision output. No
+answer within ~55 s falls through to the normal terminal prompt.
+
+Honest limits: this decides *tool permissions* only — hooks expose no way
+to answer AskUserQuestion option pickers — and Codex's notify surface has
+no decision channel at all, so it stays display-only.
+
+## How it works
+
+- The app runs an `NWListener` WebSocket server on port 8737, advertised
+  via Bonjour as `_carmoji._tcp`. LAN only; every frame must carry the
+  pairing code.
+- `carmoji.js hook` is invoked by Claude Code's hooks with the event JSON
+  on stdin, maps it to a wire event, sends one frame (≤0.9 s budget), and
+  always exits 0 — it can never slow down or break a coding session. When
+  unpaired it exits immediately.
+- Pairing state lives in `~/.config/carmoji/config.json`.

package/carmoji.js

@@ -0,0 +1,475 @@
+#!/usr/bin/env node
+// CarMoji bridge: forwards coding events from Claude Code / Codex hooks to
+// the CarMoji app over a LAN WebSocket. The phone advertises itself via
+// Bonjour as `_carmoji._tcp`; `pair` discovers it once and caches the
+// address + pairing code in ~/.config/carmoji/config.json.
+//
+// Commands:
+//   pair <code>      discover the phone on this Wi-Fi and pair with it
+//   hook             Claude Code hook entry point (reads hook JSON on stdin)
+//   codex-notify     Codex notify entry point (event JSON as last argument)
+//   test <name>      send a test event: start|prompt|edit|run|done|error|permission|end
+//   claude-config    print the .claude/settings.json hooks snippet
+//   codex-config     print the ~/.codex/config.toml notify line
+
+import {
+  readFileSync, writeFileSync, mkdirSync,
+  statSync, openSync, readSync, closeSync,
+} from 'node:fs';
+import { spawn } from 'node:child_process';
+import { homedir } from 'node:os';
+import { join, dirname, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const CONFIG_PATH = join(homedir(), '.config', 'carmoji', 'config.json');
+const SCRIPT_PATH = fileURLToPath(import.meta.url);
+// Installed through npm/npx the script lives in an ephemeral cache, so
+// printed configs must go through `npx` rather than an absolute path.
+const RUNNING_FROM_PACKAGE = SCRIPT_PATH.includes('node_modules')
+  || SCRIPT_PATH.includes('_npx');
+const HOOK_COMMAND = RUNNING_FROM_PACKAGE
+  ? 'npx -y carmoji hook'
+  : `node "${SCRIPT_PATH}" hook`;
+// Never make the user's coding session wait on us.
+const SEND_TIMEOUT_MS = 900;
+const DISCOVER_TIMEOUT_MS = 10_000;
+
+function loadConfig() {
+  try {
+    return JSON.parse(readFileSync(CONFIG_PATH, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function saveConfig(config) {
+  mkdirSync(dirname(CONFIG_PATH), { recursive: true });
+  writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + '\n');
+}
+
+function readStdin() {
+  try {
+    return readFileSync(0, 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+/** Run dns-sd (which never exits on its own) for a bounded time. */
+function runDnssd(args, ms) {
+  return new Promise((resolve) => {
+    const child = spawn('dns-sd', args);
+    let output = '';
+    child.stdout.on('data', (data) => { output += data; });
+    child.on('error', () => resolve(''));
+    setTimeout(() => {
+      child.kill();
+      resolve(output);
+    }, ms);
+  });
+}
+
+/**
+ * Discovery via macOS's own mDNSResponder. The pure-JS fallback binds
+ * multicast to one interface and goes blind on Macs with VPN tunnels and
+ * virtual adapters; dns-sd browses every interface correctly.
+ */
+async function discoverViaDnssd() {
+  const browse = await runDnssd(['-B', '_carmoji._tcp', 'local.'], 2500);
+  const names = new Set();
+  for (const line of browse.split('\n')) {
+    const match = line.match(/\sAdd\s+\d+\s+\d+\s+local\.\s+_carmoji\._tcp\.\s+(.+)$/);
+    if (match) names.add(match[1].trim());
+  }
+  const devices = [];
+  for (const name of names) {
+    const resolved = await runDnssd(['-L', name, '_carmoji._tcp', 'local.'], 2500);
+    const reach = resolved.match(/can be reached at\s+(\S+?):(\d+)/);
+    if (!reach) continue;
+    const lookup = await runDnssd(['-G', 'v4', reach[1]], 2500);
+    const address = lookup.match(/\sAdd\s.*?\s(\d+\.\d+\.\d+\.\d+)\s/);
+    if (address) devices.push({ host: address[1], port: Number(reach[2]), name });
+  }
+  return devices;
+}
+
+/**
+ * Find every CarMoji app on this network. On macOS ask mDNSResponder via
+ * dns-sd first; fall back to the JS mDNS implementation elsewhere (or if
+ * dns-sd came up empty).
+ */
+async function discoverAll() {
+  if (process.platform === 'darwin') {
+    const devices = await discoverViaDnssd();
+    if (devices.length > 0) return devices;
+  }
+  return discoverViaMulticastJS();
+}
+
+async function discoverViaMulticastJS() {
+  const { Bonjour } = await import('bonjour-service');
+  const bonjour = new Bonjour();
+  const found = new Map();
+  return new Promise((resolve) => {
+    const deadline = setTimeout(finish, DISCOVER_TIMEOUT_MS);
+    let grace = null;
+    const browser = bonjour.find({ type: 'carmoji' }, (service) => {
+      const host = (service.addresses || []).find((a) => a.includes('.'));
+      if (!host) return;
+      found.set(`${host}:${service.port}`,
+                { host, port: service.port, name: service.name });
+      grace ??= setTimeout(finish, 1500);
+    });
+    function finish() {
+      clearTimeout(deadline);
+      clearTimeout(grace);
+      browser.stop();
+      bonjour.destroy();
+      resolve([...found.values()]);
+    }
+  });
+}
+
+/** Let the user pick between several discovered phones. */
+async function chooseDevice(devices) {
+  console.log('Multiple CarMoji devices found:');
+  devices.forEach((d, i) => console.log(`  ${i + 1}. ${d.name} — ${d.host}:${d.port}`));
+  if (!process.stdin.isTTY) {
+    console.error('\nRe-run with the address of the one you want: carmoji pair <code> <ip[:port]>');
+    process.exit(1);
+  }
+  const { createInterface } = await import('node:readline/promises');
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const answer = await rl.question(`Pair with which one? [1-${devices.length}] `);
+  rl.close();
+  const device = devices[Number(answer) - 1];
+  if (!device) {
+    console.error('Invalid choice.');
+    process.exit(1);
+  }
+  return device;
+}
+
+/**
+ * Send one event frame and wait briefly for the ack.
+ * Returns "ok", an error string from the phone, or "unreachable".
+ */
+async function send(config, message) {
+  const { default: WebSocket } = await import('ws');
+  return new Promise((resolve) => {
+    const ws = new WebSocket(`ws://${config.host}:${config.port}`, {
+      handshakeTimeout: SEND_TIMEOUT_MS,
+    });
+    const timer = setTimeout(() => finish('unreachable'), SEND_TIMEOUT_MS);
+    ws.on('open', () => {
+      ws.send(JSON.stringify({ v: 1, code: config.code, ...message }));
+    });
+    ws.on('message', (data) => {
+      try {
+        const reply = JSON.parse(data.toString());
+        finish(reply.ok ? 'ok' : reply.error || 'rejected');
+      } catch {
+        finish('ok');
+      }
+    });
+    ws.on('error', () => finish('unreachable'));
+    function finish(result) {
+      clearTimeout(timer);
+      ws.terminate();
+      resolve(result);
+    }
+  });
+}
+
+/**
+ * Send an approval_request and hold the connection open until the phone
+ * answers (or the timeout passes). Resolves "allow", "deny", or null.
+ */
+async function requestApproval(config, message, timeoutMs = 55_000) {
+  const { default: WebSocket } = await import('ws');
+  return new Promise((resolve) => {
+    const ws = new WebSocket(`ws://${config.host}:${config.port}`, {
+      handshakeTimeout: SEND_TIMEOUT_MS,
+    });
+    const timer = setTimeout(() => finish(null), timeoutMs);
+    ws.on('open', () => {
+      ws.send(JSON.stringify({ v: 1, code: config.code, ...message }));
+    });
+    ws.on('message', (data) => {
+      try {
+        const reply = JSON.parse(data.toString());
+        if (reply.ok === false) return finish(null);
+        if (reply.decision === 'allow' || reply.decision === 'deny') {
+          finish(reply.decision);
+        }
+        // A plain ack means the card is up — keep waiting for the tap.
+      } catch { /* ignore unparsable frames */ }
+    });
+    ws.on('error', () => finish(null));
+    ws.on('close', () => finish(null));
+    function finish(result) {
+      clearTimeout(timer);
+      ws.terminate();
+      resolve(result);
+    }
+  });
+}
+
+function summarizeToolInput(payload) {
+  const input = payload.tool_input || {};
+  const text = input.command || input.file_path || input.description
+    || JSON.stringify(input);
+  return String(text).replace(/\s+/g, ' ').slice(0, 140);
+}
+
+/** Map a Claude Code hook payload to a wire event, or null to ignore. */
+function eventFromClaudeHook(payload) {
+  switch (payload.hook_event_name) {
+    case 'SessionStart': return { event: 'session_start' };
+    case 'UserPromptSubmit': return { event: 'prompt' };
+    case 'PreToolUse': return { event: 'tool_start', tool: payload.tool_name };
+    // tool_end doesn't animate the face; it's a session heartbeat and a
+    // fresh token sample for the tok/s readout.
+    case 'PostToolUse': return { event: 'tool_end', tool: payload.tool_name };
+    case 'Notification': return { event: 'permission' };
+    case 'Stop': return { event: 'turn_done' };
+    case 'SessionEnd': return { event: 'session_end' };
+    default: return null;
+  }
+}
+
+/**
+ * Cumulative output tokens for this session, counted incrementally from the
+ * transcript JSONL: a per-session byte offset is cached so each hook only
+ * parses lines appended since the previous one.
+ */
+function sessionTokens(payload) {
+  const transcript = payload.transcript_path;
+  const session = payload.session_id;
+  if (!transcript || !session) return undefined;
+  const statePath = join(dirname(CONFIG_PATH), 'sessions', `${session}.json`);
+  let state = { offset: 0, total: 0 };
+  try { state = JSON.parse(readFileSync(statePath, 'utf8')); } catch {}
+  let size;
+  try { size = statSync(transcript).size; } catch { return undefined; }
+  if (size < state.offset) state = { offset: 0, total: 0 }; // truncated/rotated
+  if (size > state.offset) {
+    const fd = openSync(transcript, 'r');
+    const buffer = Buffer.alloc(size - state.offset);
+    const bytesRead = readSync(fd, buffer, 0, buffer.length, state.offset);
+    closeSync(fd);
+    const chunk = buffer.subarray(0, bytesRead);
+    // Only consume complete lines; a partially-written last line is left
+    // for the next hook invocation.
+    const lastNewline = chunk.lastIndexOf(0x0a);
+    if (lastNewline >= 0) {
+      for (const line of chunk.subarray(0, lastNewline + 1).toString('utf8').split('\n')) {
+        if (!line.includes('"usage"')) continue;
+        try {
+          const usage = JSON.parse(line)?.message?.usage;
+          if (usage?.output_tokens) state.total += usage.output_tokens;
+        } catch { /* ignore malformed lines */ }
+      }
+      state.offset += lastNewline + 1;
+      mkdirSync(dirname(statePath), { recursive: true });
+      writeFileSync(statePath, JSON.stringify(state));
+    }
+  }
+  return state.total;
+}
+
+const TEST_EVENTS = {
+  start: { event: 'session_start' },
+  prompt: { event: 'prompt' },
+  edit: { event: 'tool_start', tool: 'Edit' },
+  run: { event: 'tool_start', tool: 'Bash' },
+  heartbeat: { event: 'tool_end', tool: 'Edit' },
+  done: { event: 'turn_done' },
+  error: { event: 'error' },
+  permission: { event: 'permission' },
+  end: { event: 'session_end' },
+};
+
+function claudeConfigSnippet() {
+  const entry = [{ hooks: [{ type: 'command', command: HOOK_COMMAND, timeout: 5 }] }];
+  const hooks = {};
+  for (const name of ['SessionStart', 'UserPromptSubmit', 'PreToolUse',
+                      'PostToolUse', 'Notification', 'Stop', 'SessionEnd']) {
+    hooks[name] = entry;
+  }
+  return JSON.stringify({ hooks }, null, 2);
+}
+
+async function main() {
+  const [command, arg, ...rest] = process.argv.slice(2);
+
+  switch (command) {
+    case 'pair': {
+      if (!/^\d{4}$/.test(arg || '')) {
+        console.error('Usage: carmoji pair <4-digit code from the app’s Code Buddy sheet> [ip[:port]]');
+        process.exit(1);
+      }
+      let target;
+      const manual = rest[0];
+      if (manual) {
+        // Manual addressing for networks with several phones (the app's
+        // Code Buddy sheet shows the address) or when mDNS is blocked.
+        const [host, port] = manual.split(':');
+        target = { host, port: Number(port) || 8737, name: host };
+      } else {
+        console.log('Looking for CarMoji on this network…');
+        const devices = await discoverAll();
+        if (devices.length === 0) {
+          console.error('No CarMoji found. Is the app open, "Listen on this Wi-Fi" on, and the phone on the same network?');
+          console.error('You can also pair by address: carmoji pair <code> <ip[:port]>');
+          process.exit(1);
+        }
+        target = devices.length === 1 ? devices[0] : await chooseDevice(devices);
+      }
+      const config = { host: target.host, port: target.port, code: arg };
+      const result = await send(config, { source: 'bridge', event: 'turn_done' });
+      if (result !== 'ok') {
+        console.error(result === 'bad-code'
+          ? `"${target.name}" (${target.host}:${target.port}) rejected the pairing code — check that device’s Code Buddy sheet. (Wrong phone? Pass its address: carmoji pair <code> <ip[:port]>)`
+          : `Found "${target.name}" at ${target.host}:${target.port} but couldn’t talk to it (${result}).`);
+        process.exit(1);
+      }
+      saveConfig(config);
+      console.log(`Paired with "${target.name}" at ${target.host}:${target.port} — the pet should be celebrating!`);
+      break;
+    }
+
+    case 'hook': {
+      // Runs inside Claude Code on every hook — must be silent, quick, and
+      // always exit 0 so it can never disturb the session.
+      try {
+        const config = loadConfig();
+        if (!config) break;
+        const payload = JSON.parse(readStdin() || '{}');
+
+        // Gate mode (opt-in, see `gate-config`): PreToolUse blocks while
+        // the phone shows Allow/Deny; the printed JSON settles the
+        // permission. Timeout falls through to the normal terminal prompt.
+        if (arg === '--gate' && payload.hook_event_name === 'PreToolUse') {
+          const decision = await requestApproval(config, {
+            source: 'claude',
+            session: payload.session_id,
+            event: 'approval_request',
+            tool: payload.tool_name,
+            detail: summarizeToolInput(payload),
+            project: payload.cwd ? basename(payload.cwd) : undefined,
+          });
+          if (decision) {
+            console.log(JSON.stringify({
+              hookSpecificOutput: {
+                hookEventName: 'PreToolUse',
+                permissionDecision: decision,
+                permissionDecisionReason: decision === 'allow'
+                  ? 'Approved from CarMoji'
+                  : 'Denied from CarMoji',
+              },
+            }));
+          }
+          break;
+        }
+
+        const event = eventFromClaudeHook(payload);
+        if (!event) break;
+        const message = { source: 'claude', session: payload.session_id, ...event };
+        const tokens = sessionTokens(payload);
+        if (tokens !== undefined) message.tokens = tokens;
+        if (payload.cwd) message.project = basename(payload.cwd);
+        // A snippet of human-readable context for the phone to show.
+        const detail = payload.hook_event_name === 'UserPromptSubmit' ? payload.prompt
+          : payload.hook_event_name === 'Notification' ? payload.message
+          : undefined;
+        if (detail) message.detail = String(detail).replace(/\s+/g, ' ').slice(0, 140);
+        await send(config, message);
+      } catch {
+        // Never surface errors into the coding session.
+      }
+      break;
+    }
+
+    case 'codex-notify': {
+      try {
+        const config = loadConfig();
+        if (!config) break;
+        const payload = JSON.parse(process.argv[process.argv.length - 1] || '{}');
+        if (payload.type === 'agent-turn-complete') {
+          const session = payload['conversation-id'] || payload.conversation_id;
+          const message = { source: 'codex', session, event: 'turn_done' };
+          if (payload.cwd) message.project = basename(payload.cwd);
+          await send(config, message);
+        }
+      } catch {
+        // Same rule as `hook`: stay silent.
+      }
+      break;
+    }
+
+    case 'test': {
+      const event = TEST_EVENTS[arg];
+      if (!event) {
+        console.error(`Usage: carmoji test <${Object.keys(TEST_EVENTS).join('|')}> [session] [tokens]`);
+        process.exit(1);
+      }
+      const config = loadConfig();
+      if (!config) {
+        console.error('Not paired yet — run: carmoji pair <code>');
+        process.exit(1);
+      }
+      const [session, tokens, project] = rest;
+      const message = { source: 'test', session, ...event };
+      if (tokens !== undefined) message.tokens = Number(tokens);
+      if (project) message.project = project;
+      const result = await send(config, message);
+      console.log(result === 'ok' ? 'Sent!' : `Failed: ${result}`);
+      process.exit(result === 'ok' ? 0 : 1);
+      break;
+    }
+
+    case 'discover': {
+      console.log('Looking for CarMoji devices on this network…');
+      const devices = await discoverAll();
+      if (devices.length === 0) {
+        console.log('None found. Check the app is open with "Listen on this Wi-Fi" on; you can always pair by address.');
+        process.exit(1);
+      }
+      devices.forEach((d) => console.log(`  ${d.name} — ${d.host}:${d.port}`));
+      break;
+    }
+
+    case 'claude-config':
+      console.log('Merge this into the project’s .claude/settings.json (or ~/.claude/settings.json for everywhere):\n');
+      console.log(claudeConfigSnippet());
+      break;
+
+    case 'codex-config':
+      console.log('Add this line to ~/.codex/config.toml:\n');
+      console.log(RUNNING_FROM_PACKAGE
+        ? 'notify = ["npx", "-y", "carmoji", "codex-notify"]'
+        : `notify = ["node", "${SCRIPT_PATH}", "codex-notify"]`);
+      break;
+
+    case 'gate-config':
+      console.log('Opt-in: answer Claude Code permission prompts from the phone.');
+      console.log('Merge into .claude/settings.json, adjusting the matcher to the tools you want gated:\n');
+      console.log(JSON.stringify({
+        hooks: {
+          PreToolUse: [{
+            matcher: 'Bash',
+            hooks: [{ type: 'command', command: `${HOOK_COMMAND} --gate`, timeout: 60 }],
+          }],
+        },
+      }, null, 2));
+      console.log('\nNotes: allow/deny from the phone settles the permission;');
+      console.log('no answer within ~55s falls through to the terminal prompt as usual.');
+      break;
+
+    default:
+      console.log('carmoji bridge — usage: pair <code> [ip[:port]] | discover | test <event> | hook [--gate] | codex-notify | claude-config | codex-config | gate-config');
+  }
+}
+
+main().then(() => process.exit(process.exitCode ?? 0));

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "carmoji",
+  "version": "0.1.0",
+  "description": "Bring your CarMoji pet to life from Claude Code / Codex — a LAN bridge that streams coding events to the CarMoji iOS app",
+  "type": "module",
+  "bin": {
+    "carmoji": "./carmoji.js"
+  },
+  "files": [
+    "carmoji.js",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/qiudaomao/CarMoji.git",
+    "directory": "bridge"
+  },
+  "keywords": [
+    "claude-code",
+    "codex",
+    "desk-pet",
+    "ios",
+    "websocket",
+    "bonjour",
+    "hooks"
+  ],
+  "author": "Qiu Daomao",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "bonjour-service": "^1.2.1",
+    "ws": "^8.18.0"
+  }
+}