carmoji 0.3.14 → 0.3.16

package/README.md

@@ -49,23 +49,25 @@ approval.
 To get reactions in every project:
 
 ```sh
-npx carmoji install claude
+npx carmoji hook claude
 ```
 
 merges the hooks into `~/.claude/settings.json`, preserving everything
-already there (a backup is saved to `settings.json.bak` first, reruns are
-no-ops, and a file that doesn't parse is refused untouched). Prefer to do
+already there (a backup is saved to `settings.json.bak` first, reruns replace
+only CarMoji-owned entries, and a file that doesn't parse is refused untouched). Prefer to do
 it by hand? `npx carmoji config claude` prints the snippet instead. Every
-command answers `--help`; `npx carmoji hook --help` documents the JSON the
-hook accepts, and `npx carmoji uninstall <tool>|all` takes it all out again.
+command answers `--help`; `npx carmoji hook --help` documents both setup and
+the JSON event mode used by installed hooks. `npx carmoji unhook <tool>|all`
+removes tool integrations again.
 
 ## All the other tools
 
 ```sh
 npx carmoji tools          # what's supported, what's detected
-npx carmoji install codex  # one tool…
-npx carmoji install all    # …or hooks for everything found on this machine
-npx carmoji uninstall <tool>
+npx carmoji hook codex     # one tool…
+npx carmoji hook all       # …or hooks for everything found on this machine
+npx carmoji unhook <tool>  # remove one tool's integration
+npx carmoji uninstall      # remove ~/.config/carmoji/carmoji.js
 ```
 
 | Tool | Hooks written to | Notes |
@@ -85,12 +87,22 @@ npx carmoji uninstall <tool>
 
 Everything merges non-destructively: a backup is written next to each
 config, reruns are idempotent, only carmoji-owned entries are ever
-removed, and unparseable files are refused untouched. `install all` skips
+removed, and unparseable files are refused untouched. `hook all` skips
 tools that aren't on the machine.
 
-Codex requires new or changed command hooks to be trusted. After installing,
+Every `carmoji hook <tool>|all` also refreshes a persistent hook runtime
+at `~/.config/carmoji/carmoji.js`, with its Node package metadata and
+dependencies beside it. Installed hooks call that file directly with
+`node`; they do not run `npx`, contact npm, or depend on npx's temporary
+cache during an agent session. Run `npx carmoji hook …` again whenever
+you want to update both the runtime and the selected tool's hooks. Pairing
+state in the same directory is preserved. `npx carmoji uninstall` removes
+the runtime script but preserves pairing state and tool configs; use
+`npx carmoji unhook <tool>|all` for those configs.
+
+Codex requires new or changed command hooks to be trusted. After hooking,
 open `/hooks` in Codex, review the CarMoji commands, and trust them. The
-installer removes a direct legacy CarMoji `notify` command, or removes only
+setup command removes a direct legacy CarMoji `notify` command, or removes only
 CarMoji when another notifier has it chained via `--previous-notify`.
 
 All of them funnel through the same `carmoji hook` entry point
@@ -99,7 +111,7 @@ whose payloads lack one), so the pet reacts identically no matter which
 agent is working — each with its own colored dot on the dashboard.
 
 Older Codex versions without hooks support can still use
-`npx carmoji install-codex-notify`, which sets the `notify` program in
+`npx carmoji hook-codex-notify`, which sets the `notify` program in
 `~/.codex/config.toml` (turn completions only). OpenCode users running the
 community **omo** plugin get events for free — omo fires your Claude Code
 hooks, which already carry carmoji.
@@ -155,7 +167,7 @@ Recomputed at turn boundaries with a 5-minute cache so hooks stay fast.
 
 ## Answer permissions from the phone (Claude Code and Codex)
 
-`carmoji install claude` and `carmoji install codex` hook each agent's
+`carmoji hook claude` and `carmoji hook codex` hook each agent's
 `PermissionRequest` event, which fires **only when a permission dialog is
 about to appear** —
 allowlisted tools and auto-accepted edits never trigger it, so nothing
@@ -185,8 +197,7 @@ matcher (e.g. `Bash`). Unlike `PermissionRequest`, that variant fires on
 - 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 the coding agent's hooks with 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.
+- `~/.config/carmoji/carmoji.js hook` is invoked by the coding agent's hooks
+  with event JSON on stdin, maps it to wire events, gives each delivery batch
+  a ≤0.9 s budget, and always exits 0. When unpaired it exits immediately.
 - Pairing state lives in `~/.config/carmoji/config.json`.

package/carmoji.js

@@ -9,8 +9,9 @@
 //                    whose Code Buddy sheet shows <code>
 //                    (pairing is additive — events fan out to every device)
 //   unpair [device]  forget a paired device by name or ip[:port], or `all`
-//   install <tool>|all    install hooks for a tool (or every detected one)
-//   uninstall <tool>|all  remove CarMoji hooks from a tool's config
+//   hook <tool>|all       install hooks for a tool (or every detected one)
+//   unhook <tool>|all     remove CarMoji hooks from a tool's config
+//   uninstall             remove the persistent hook runtime
 //   tools            list supported tools and where their hooks live
 //   hook             hook entry point, all tools (reads hook JSON on stdin;
 //                    --source <tool>, --event <name>, --gate)
@@ -25,26 +26,125 @@
 import {
   readFileSync, writeFileSync, mkdirSync,
   statSync, openSync, readSync, closeSync,
-  copyFileSync, existsSync, readdirSync, unlinkSync, realpathSync,
+  copyFileSync, cpSync, existsSync, readdirSync, unlinkSync, realpathSync,
+  renameSync,
 } from 'node:fs';
 import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
 import { homedir, hostname } 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 RUNTIME_DIR = dirname(CONFIG_PATH);
+const RUNTIME_SCRIPT_PATH = join(RUNTIME_DIR, 'carmoji.js');
+const RUNTIME_PACKAGE_PATH = join(RUNTIME_DIR, 'package.json');
+const RUNTIME_NODE_MODULES = join(RUNTIME_DIR, 'node_modules');
 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 REQUIRE = createRequire(import.meta.url);
 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 nodeCommand(path, subcommand) {
+  return `node ${JSON.stringify(path)} ${subcommand}`;
+}
+
+function runtimeHookCommand() {
+  return nodeCommand(RUNTIME_SCRIPT_PATH, 'hook');
+}
+
+/** Manual config snippets prefer the installed runtime, but remain useful on
+ *  a fresh machine before the first `hook <tool>` command. */
+function hookCommand() {
+  if (existsSync(RUNTIME_SCRIPT_PATH)) return runtimeHookCommand();
+  return RUNNING_FROM_PACKAGE
+    ? 'npx -y carmoji hook'
+    : nodeCommand(SCRIPT_PATH, 'hook');
+}
+
+/** Find the npm installation containing CarMoji's runtime dependencies. */
+function dependencyRoot() {
+  let path = dirname(REQUIRE.resolve('ws'));
+  while (dirname(path) !== path) {
+    if (basename(path) === 'node_modules') return path;
+    path = dirname(path);
+  }
+  throw new Error('could not locate CarMoji dependencies');
+}
+
+function samePath(left, right) {
+  try {
+    return realpathSync(left) === realpathSync(right);
+  } catch {
+    return false;
+  }
+}
+
+/** Replace one runtime file only after its complete new copy is on disk. */
+function installRuntimeFile(source, destination, fallback) {
+  if (samePath(source, destination)) return;
+  const temporary = `${destination}.tmp-${process.pid}`;
+  try {
+    if (source && existsSync(source)) copyFileSync(source, temporary);
+    else writeFileSync(temporary, fallback);
+    renameSync(temporary, destination);
+  } catch (error) {
+    try { unlinkSync(temporary); } catch { /* nothing staged */ }
+    throw error;
+  }
+}
+
+/**
+ * Install a network-independent hook runtime. `npx carmoji hook …` may run
+ * from an ephemeral npm cache, so every setup refreshes the script, its ESM
+ * package marker, and the dependencies beside the user's persistent config.
+ * Pairing state and transcript caches in the same directory are untouched.
+ */
+function installRuntime() {
+  mkdirSync(RUNTIME_DIR, { recursive: true });
+  const existed = existsSync(RUNTIME_SCRIPT_PATH);
+  try {
+    const sourceModules = dependencyRoot();
+    if (!samePath(sourceModules, RUNTIME_NODE_MODULES)) {
+      cpSync(sourceModules, RUNTIME_NODE_MODULES, {
+        recursive: true,
+        force: true,
+      });
+    }
+    const sourcePackage = join(dirname(SCRIPT_PATH), 'package.json');
+    installRuntimeFile(sourcePackage, RUNTIME_PACKAGE_PATH,
+      '{"name":"carmoji-runtime","private":true,"type":"module"}\n');
+    // Install the entry point last: an old script can use updated dependencies,
+    // while a new script must never become visible before its dependencies do.
+    installRuntimeFile(SCRIPT_PATH, RUNTIME_SCRIPT_PATH);
+  } catch (error) {
+    console.error(`Could not install the CarMoji hook runtime in ${RUNTIME_DIR}: ${error.message}`);
+    process.exit(1);
+  }
+  console.log(`${existed ? 'Updated' : 'Installed'} CarMoji hook runtime at ${RUNTIME_SCRIPT_PATH}`);
+}
+
+/** Remove only the executable runtime. Pairing state, caches, and staged
+ *  dependencies stay in place so a later `hook <tool>` can restore it without
+ *  erasing the user's devices. Tool configs are managed separately by unhook. */
+function uninstallRuntime() {
+  if (!existsSync(RUNTIME_SCRIPT_PATH)) {
+    console.log(`CarMoji hook runtime is not installed at ${RUNTIME_SCRIPT_PATH}`);
+    return;
+  }
+  try {
+    unlinkSync(RUNTIME_SCRIPT_PATH);
+  } catch (error) {
+    console.error(`Could not remove ${RUNTIME_SCRIPT_PATH}: ${error.message}`);
+    process.exit(1);
+  }
+  console.log(`Removed CarMoji hook runtime from ${RUNTIME_SCRIPT_PATH}`);
+  console.log('Run `carmoji unhook <tool>|all` separately to remove tool configuration.');
+}
+
 function loadConfig() {
   try {
     return JSON.parse(readFileSync(CONFIG_PATH, 'utf8'));
@@ -532,8 +632,19 @@ function eventFromHook(payload) {
     case 'PostToolUse': return { event: 'tool_end', tool };
     case 'PostToolUseFailure':
     case 'Error': return { event: 'error' };
-    case 'PermissionRequest':
-    case 'Notification': return { event: 'permission', tool };
+    case 'PermissionRequest': return { event: 'permission', tool };
+    case 'Notification': {
+      // Claude Code routes several nudges through this one hook. Only a
+      // real permission prompt deserves the phone's pleading face; the
+      // "waiting for your input" idle reminder lands a minute after a
+      // *finished* reply, and mapping it to permission flipped "done"
+      // into "blocked". Anything not clearly a permission stays a bare
+      // heartbeat.
+      const note = firstString(payload.message, payload.detail) ?? '';
+      return /permission|approv/i.test(note)
+        ? { event: 'permission', tool }
+        : { event: 'tool_end' };
+    }
     case 'Stop': return { event: 'turn_done' };
     case 'SessionEnd': return { event: 'session_end' };
     // Liveness only: keep the session fresh without a face reaction.
@@ -738,7 +849,7 @@ const CURSOR_STYLE_EVENTS = [
 ];
 
 /**
- * Every tool `carmoji install <name>` knows. `source` defaults to the key;
+ * Every tool `carmoji hook <name>` knows. `source` defaults to the key;
  * `timeoutMs` marks tools whose hook timeouts are milliseconds; `eventFlag`
  * marks tools whose stdin lacks the event name (the command carries
  * `--event <name>`); `requiresDir` gates installation on the tool actually
@@ -827,7 +938,7 @@ function installJsonHooks(key, tool) {
   const hooks = (root.hooks && typeof root.hooks === 'object' && !Array.isArray(root.hooks))
     ? root.hooks : {};
   const source = tool.source ?? key;
-  const base = `${HOOK_COMMAND} --source ${source}`;
+  const base = `${runtimeHookCommand()} --source ${source}`;
   const timeout = (seconds) => (tool.timeoutMs ? seconds * 1000 : seconds);
 
   // Remove every old CarMoji entry first, including events no longer in this
@@ -904,7 +1015,7 @@ function installKimiHooks(key, tool) {
   const path = join(homedir(), tool.config);
   let contents = existsSync(path) ? readFileSync(path, 'utf8') : '';
   contents = removeKimiBlocks(contents);
-  const command = `${HOOK_COMMAND} --source kimi`.replace(/"/g, '\\"');
+  const command = `${runtimeHookCommand()} --source kimi`.replace(/"/g, '\\"');
   const blocks = tool.events.map((event) => {
     const toolEvent = ['PreToolUse', 'PostToolUse', 'PostToolUseFailure'].includes(event);
     return `[[hooks]]\nevent = "${event}"\ncommand = "${command}"\ntimeout = 5`
@@ -924,7 +1035,7 @@ function installClineHooks(key, tool) {
   mkdirSync(dir, { recursive: true });
   const script = '#!/bin/sh\n'
     + '# carmoji hook — forwards Cline events to the CarMoji pet\n'
-    + `exec ${HOOK_COMMAND} --source cline\n`;
+    + `exec ${runtimeHookCommand()} --source cline\n`;
   for (const event of tool.events) {
     const path = join(dir, event);
     if (existsSync(path) && !readFileSync(path, 'utf8').includes('carmoji')) {
@@ -1060,7 +1171,7 @@ function uninstallTool(key, { skipMissing = false } = {}) {
     console.error(`Unknown tool "${key}". Known: ${Object.keys(TOOLS).join(', ')}`);
     process.exit(1);
   }
-  // `uninstall all` sweeps every known tool; stay quiet about the ones that
+  // `unhook all` sweeps every known tool; stay quiet about the ones that
   // were never installed instead of printing 14 "nothing installed" lines.
   const nothing = () => {
     if (!skipMissing) console.log(`${tool.name}: nothing installed.`);
@@ -1108,9 +1219,8 @@ function uninstallTool(key, { skipMissing = false } = {}) {
 
 /**
  * Merge the CarMoji hooks into ~/.claude/settings.json, keeping a backup.
- * Existing carmoji entries are replaced, not skipped, so switching between
- * a repo clone (`node …/carmoji.js`) and the npm package (`npx carmoji`)
- * always leaves the config pointing at whichever one ran the install.
+ * Existing carmoji entries are replaced, not skipped, so every reinstall
+ * points at the freshly staged runtime in ~/.config/carmoji.
  */
 function installClaude() {
   installJsonHooks('claude', TOOLS.claude);
@@ -1121,9 +1231,9 @@ function installClaude() {
  *  Codex versions without hooks.json support), keeping a backup. */
 function installCodexNotify() {
   const path = join(codexHome(), 'config.toml');
-  const notifyLine = RUNNING_FROM_PACKAGE
-    ? 'notify = ["npx", "-y", "carmoji", "codex-notify"]'
-    : `notify = ["node", "${SCRIPT_PATH}", "codex-notify"]`;
+  const notifyLine = `notify = ${JSON.stringify([
+    'node', RUNTIME_SCRIPT_PATH, 'codex-notify',
+  ])}`;
 
   let text = existsSync(path) ? readFileSync(path, 'utf8') : '';
   const lines = text.split('\n');
@@ -1152,7 +1262,7 @@ function claudeConfigSnippet() {
   const hooks = {};
   for (const name of CLAUDE_HOOK_EVENTS) {
     const timeout = name === 'PermissionRequest' ? PERMISSION_HOOK_TIMEOUT_S : 5;
-    hooks[name] = [{ hooks: [{ type: 'command', command: HOOK_COMMAND, timeout }] }];
+    hooks[name] = [{ hooks: [{ type: 'command', command: hookCommand(), timeout }] }];
   }
   return JSON.stringify({ hooks }, null, 2);
 }
@@ -1291,6 +1401,27 @@ async function main() {
     }
 
     case 'hook': {
+      // Setup mode overloads the event entry point deliberately:
+      //   carmoji hook codex          writes Codex's hook config
+      //   carmoji hook --source codex receives one event on stdin
+      // Installed hooks always start with a flag, so the two paths cannot
+      // be confused.
+      if (arg && !arg.startsWith('-')) {
+        if (arg !== 'all' && !TOOLS[arg]) {
+          console.error(`Unknown tool "${arg}". Known: ${Object.keys(TOOLS).join(', ')}`);
+          process.exit(1);
+        }
+        installRuntime();
+        if (arg === 'all') {
+          for (const key of Object.keys(TOOLS)) {
+            installTool(key, { skipMissing: true });
+          }
+          break;
+        }
+        installTool(arg);
+        break;
+      }
+
       // Runs inside the coding agent on every hook — must be silent, quick,
       // and always exit 0 so it can never disturb the session. The two
       // deliberate exceptions hold the hook open while the phone answers:
@@ -1620,38 +1751,36 @@ async function main() {
       break;
     }
 
-    case 'install': {
+    case 'unhook': {
       if (arg === 'all') {
         for (const key of Object.keys(TOOLS)) {
-          installTool(key, { skipMissing: true });
+          uninstallTool(key, { skipMissing: true });
         }
         break;
       }
       if (!arg) {
-        console.log(`Usage: carmoji install <tool>|all\nTools: ${Object.keys(TOOLS).join(', ')}`);
+        console.log(`Usage: carmoji unhook <tool>|all\nTools: ${Object.keys(TOOLS).join(', ')}`);
         process.exit(1);
       }
-      installTool(arg);
+      uninstallTool(arg);
       break;
     }
 
-    case 'uninstall': {
-      if (arg === 'all') {
-        for (const key of Object.keys(TOOLS)) {
-          uninstallTool(key, { skipMissing: true });
-        }
-        break;
-      }
-      if (!arg) {
-        console.log(`Usage: carmoji uninstall <tool>|all\nTools: ${Object.keys(TOOLS).join(', ')}`);
+    case 'uninstall':
+      if (arg) {
+        console.error('`carmoji uninstall` takes no arguments. Use `carmoji unhook <tool>|all` to remove hooks.');
         process.exit(1);
       }
-      uninstallTool(arg);
+      uninstallRuntime();
+      break;
+
+    case 'install':
+      console.error('`carmoji install <tool>|all` was renamed to `carmoji hook <tool>|all`.');
+      process.exit(1);
       break;
-    }
 
     case 'tools': {
-      console.log('Supported tools (carmoji install <tool>):');
+      console.log('Supported tools (carmoji hook <tool>):');
       for (const [key, tool] of Object.entries(TOOLS)) {
         const where = key === 'codex' ? '$CODEX_HOME/hooks.json' : `~/${tool.config}`;
         const found = isToolPresent(key, tool) ? '' : '  (not detected)';
@@ -1667,16 +1796,23 @@ async function main() {
       else printHelp('config');
       break;
 
-    case 'install-codex-notify':
+    case 'hook-codex-notify':
+      installRuntime();
       installCodexNotify();
       break;
 
     // Hidden back-compat aliases — the app's setup sheet and old READMEs
     // print these spellings, so they must keep working.
+    case 'install-codex-notify':
+      installRuntime();
+      installCodexNotify();
+      break;
     case 'install-claude':
+      installRuntime();
       installTool('claude');
       break;
     case 'install-codex':
+      installRuntime();
       installTool('codex');
       break;
     case 'claude-config':
@@ -1696,21 +1832,24 @@ async function main() {
 
 function printClaudeConfig() {
   console.log('Merge this into the project’s .claude/settings.json (or ~/.claude/settings.json for everywhere):\n');
-  console.log('(Or let `carmoji install claude` do it for you, with a backup.)\n');
+  console.log('(Or let `carmoji hook claude` do it for you, with a backup.)\n');
   console.log(claudeConfigSnippet());
 }
 
 function printCodexConfig() {
   console.log('Modern Codex reads hooks from $CODEX_HOME/hooks.json — prefer:');
-  console.log('  carmoji install codex\n');
+  console.log('  carmoji hook codex\n');
   console.log('For older Codex versions, 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"]`);
+  const program = existsSync(RUNTIME_SCRIPT_PATH)
+    ? ['node', RUNTIME_SCRIPT_PATH, 'codex-notify']
+    : RUNNING_FROM_PACKAGE
+      ? ['npx', '-y', 'carmoji', 'codex-notify']
+      : ['node', SCRIPT_PATH, 'codex-notify'];
+  console.log(`notify = ${JSON.stringify(program)}`);
 }
 
 function printGateConfig() {
-  console.log('Legacy/advanced: `carmoji install claude` now installs a PermissionRequest');
+  console.log('Legacy/advanced: `carmoji hook claude` now installs a PermissionRequest');
   console.log('hook that answers real permission prompts from the phone by itself.');
   console.log('The PreToolUse gate below instead fires on EVERY matched tool call, even');
   console.log('allowlisted ones — useful only on older Claude Code versions without the');
@@ -1720,7 +1859,7 @@ function printGateConfig() {
     hooks: {
       PreToolUse: [{
         matcher: 'Bash',
-        hooks: [{ type: 'command', command: `${HOOK_COMMAND} --gate`, timeout: 60 }],
+        hooks: [{ type: 'command', command: `${hookCommand()} --gate`, timeout: 60 }],
       }],
     },
   }, null, 2));
@@ -1733,11 +1872,12 @@ const USAGE = `carmoji bridge — talk to the CarMoji app on your phone
   pair <code> [ip[:port]]      pair with a phone (code from its Code Buddy sheet)
   unpair [<name|ip[:port]>|all]  forget paired devices
   discover                     list CarMoji devices on this Wi-Fi
-  install <tool>|all           install hooks (tools: ${Object.keys(TOOLS).join(', ')})
-  uninstall <tool>|all         remove CarMoji hooks from a tool's config
+  hook <tool>|all              install/update hooks (tools: ${Object.keys(TOOLS).join(', ')})
+  unhook <tool>|all            remove CarMoji hooks from a tool's config
+  uninstall                    remove ~/.config/carmoji/carmoji.js
   tools                        show each tool's config path and whether it's present
   test <event>                 send a fake event; \`test approval\` pops the Allow/Deny card
-  hook                         entry point the agents' hooks invoke (reads JSON on stdin)
+  hook [--source <tool>]       event entry point used by installed hooks (reads stdin)
   config <claude|codex|gate>   print a manual config snippet
   codex-notify                 legacy Codex notify entry point
 
@@ -1748,11 +1888,20 @@ accepted stdin JSON, \`carmoji test --help\` lists every test event.`;
 function printHelp(topic) {
   switch (topic) {
     case 'hook':
-      console.log(`carmoji hook [--source <tool>] [--event <name>] [--gate]
+      console.log(`carmoji hook <tool>|all
+carmoji hook [--source <tool>] [--event <name>] [--gate]
+
+With a tool name, installs or updates the network-independent runtime at
+~/.config/carmoji/carmoji.js and writes that tool's hook configuration.
+The \`all\` target hooks every supported tool detected on this machine. Re-running the
+command updates the runtime and replaces earlier CarMoji-owned entries.
+
+Tools: ${Object.keys(TOOLS).join(', ')}
 
-Entry point the coding agents' hooks invoke: reads ONE hook event as JSON on
-stdin, forwards it to every paired phone, and exits 0 no matter what so it can
-never disturb a session. Unpaired = immediate no-op.
+Without a tool name, this is the event entry point used by those installed
+hooks. It reads ONE hook event as JSON on stdin, forwards it to every paired
+phone, and exits 0 no matter what so it can never disturb a session.
+Unpaired event delivery = immediate no-op.
 
 Flags:
   --source <tool>  which agent is calling (default: claude) — sets the wire
@@ -1821,34 +1970,36 @@ without a coding agent.
     case 'config':
       console.log(`carmoji config <claude|codex|gate>
 
-  claude  the .claude/settings.json hooks snippet (what \`install claude\`
+  claude  the .claude/settings.json hooks snippet (what \`hook claude\`
           writes, including the ${PERMISSION_HOOK_TIMEOUT_S}s PermissionRequest hook)
   codex   the legacy ~/.codex/config.toml notify line for Codex versions
-          without hooks.json (modern Codex: \`carmoji install codex\`)
+          without hooks.json (modern Codex: \`carmoji hook codex\`)
   gate    the legacy PreToolUse gate snippet — fires on every matched call;
-          superseded by the PermissionRequest hook \`install claude\` sets up`);
+          superseded by the PermissionRequest hook \`hook claude\` sets up`);
       break;
 
     case 'install':
-      console.log(`carmoji install <tool>|all
-
-Writes CarMoji's hooks into the tool's own config (a .bak backup is saved
-next to anything modified; reinstalling replaces earlier CarMoji entries).
-\`all\` installs into every tool detected on this machine.
-
-Tools: ${Object.keys(TOOLS).join(', ')}
-\`carmoji tools\` shows each one's config path and whether it's present.`);
+      console.log('`carmoji install <tool>|all` was renamed to `carmoji hook <tool>|all`.');
       break;
 
-    case 'uninstall':
-      console.log(`carmoji uninstall <tool>|all
+    case 'unhook':
+      console.log(`carmoji unhook <tool>|all
 
 Removes every CarMoji entry from the tool's hook config, leaving other
-hooks untouched. \`all\` sweeps every known tool quietly.
+hooks untouched. \`all\` sweeps every known tool quietly. It does not remove
+the persistent runtime; use \`carmoji uninstall\` for that.
 
 Tools: ${Object.keys(TOOLS).join(', ')}`);
       break;
 
+    case 'uninstall':
+      console.log(`carmoji uninstall
+
+Removes ~/.config/carmoji/carmoji.js. Pairing state and caches are preserved.
+This does not edit any tool config; run \`carmoji unhook <tool>|all\` first if
+you also want to remove installed hooks.`);
+      break;
+
     default:
       console.log(USAGE);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "carmoji",
-  "version": "0.3.14",
+  "version": "0.3.16",
   "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": {