storymode-cli 1.1.1 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "storymode-cli",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Play AI-animated pixel art characters in your terminal",
   "type": "module",
   "bin": {

package/src/api.mjs

@@ -28,11 +28,12 @@ export async function fetchGallery() {
   return JSON.parse(buffer.toString('utf-8'));
 }
 
-export async function fetchFrames(galleryId, { size, mode } = {}) {
+export async function fetchFrames(galleryId, { size, mode, animId } = {}) {
   let url = `${BASE}/gallery/${galleryId}/frames`;
   const params = [];
   if (size && size !== 'full') params.push(`size=${size}`);
   if (mode) params.push(`mode=${mode}`);
+  if (animId) params.push(`anim_id=${animId}`);
   if (params.length) url += '?' + params.join('&');
   const { buffer, contentType } = await request(url);
   let json;

package/src/cache.mjs

@@ -0,0 +1,147 @@
+import { mkdirSync, readdirSync, readFileSync, writeFileSync, rmSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { fetchFrames, fetchCharacter } from './api.mjs';
+
+const STORYMODE_DIR = join(homedir(), '.storymode');
+
+export function getCacheDir(galleryId, size = 'compact') {
+  return join(STORYMODE_DIR, 'cache', String(galleryId), size);
+}
+
+export function getLocalDir(galleryId) {
+  return join(STORYMODE_DIR, 'local', String(galleryId));
+}
+
+/** Read all cached animation JSONs from disk. Returns Map<name, {fps, frames}> */
+export function readCached(galleryId, size) {
+  const dir = getCacheDir(galleryId, size);
+  const map = new Map();
+  if (!existsSync(dir)) return map;
+  for (const file of readdirSync(dir)) {
+    if (!file.endsWith('.json') || file === 'character.json') continue;
+    try {
+      const data = JSON.parse(readFileSync(join(dir, file), 'utf-8'));
+      const name = file.replace(/\.json$/, '').replace(/-/g, ' ');
+      map.set(name, data);
+    } catch {
+      // Corrupted cache file — skip it
+    }
+  }
+  return map;
+}
+
+/** Write a single animation JSON to cache */
+export function writeCache(galleryId, name, data, size) {
+  const dir = getCacheDir(galleryId, size);
+  mkdirSync(dir, { recursive: true });
+  const filename = name.replace(/ /g, '-') + '.json';
+  writeFileSync(join(dir, filename), JSON.stringify(data));
+}
+
+/** Write character.json to cache */
+export function writeCacheCharacter(galleryId, character, size) {
+  const dir = getCacheDir(galleryId, size);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, 'character.json'), JSON.stringify(character));
+}
+
+/** Read cached character.json */
+export function readCachedCharacter(galleryId, size) {
+  const file = join(getCacheDir(galleryId, size), 'character.json');
+  if (!existsSync(file)) return null;
+  try {
+    return JSON.parse(readFileSync(file, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+/** Read local animation overrides. Returns Map<name, {fps, frames}> */
+export function readLocalOverrides(galleryId) {
+  const dir = getLocalDir(galleryId);
+  const map = new Map();
+  if (!existsSync(dir)) return map;
+  for (const file of readdirSync(dir)) {
+    if (!file.endsWith('.json')) continue;
+    try {
+      const data = JSON.parse(readFileSync(join(dir, file), 'utf-8'));
+      const name = file.replace(/\.json$/, '').replace(/-/g, ' ');
+      map.set(name, data);
+    } catch {
+      // Skip corrupted files
+    }
+  }
+  return map;
+}
+
+/**
+ * Load all animations for a gallery: local overrides > cache > server fetch.
+ * Returns { animMap: Map<name, {fps, frames}>, character }
+ */
+export async function loadAnimations(galleryId, { size = 'compact', mode } = {}) {
+  const localOverrides = readLocalOverrides(galleryId);
+  const cached = readCached(galleryId, size);
+  let character = readCachedCharacter(galleryId, size);
+
+  // If we have cached data and character, use it (fetch updates in background)
+  const hasCached = cached.size > 0 && character;
+
+  if (!hasCached) {
+    // Must fetch from server
+    character = await fetchCharacter(galleryId);
+    writeCacheCharacter(galleryId, character, size);
+
+    const anims = character.animations || [];
+    const total = anims.length;
+    let loaded = 0;
+
+    process.stderr.write(`  Loading animations... 0/${total}\r`);
+
+    // Fetch all animations in parallel
+    const results = await Promise.all(
+      anims.map(async (anim) => {
+        const fetchOpts = { size, animId: anim.id };
+        if (mode) fetchOpts.mode = mode;
+        const data = await fetchFrames(galleryId, fetchOpts);
+        loaded++;
+        process.stderr.write(`  Loading animations... ${loaded}/${total}\r`);
+        return { name: anim.name, data };
+      })
+    );
+
+    process.stderr.write(`  Loading animations... ${total}/${total} done.\n`);
+
+    for (const { name, data } of results) {
+      cached.set(name, data);
+      writeCache(galleryId, name, data, size);
+    }
+  }
+
+  // Merge: local overrides win over cache
+  const animMap = new Map(cached);
+  for (const [name, data] of localOverrides) {
+    animMap.set(name, data);
+  }
+
+  return { animMap, character };
+}
+
+/** Delete cache for one or all characters */
+export function clearCache(galleryId) {
+  if (galleryId) {
+    const dir = getCacheDir(galleryId);
+    if (existsSync(dir)) {
+      rmSync(dir, { recursive: true });
+      return true;
+    }
+    return false;
+  }
+  // Clear all
+  const cacheRoot = join(STORYMODE_DIR, 'cache');
+  if (existsSync(cacheRoot)) {
+    rmSync(cacheRoot, { recursive: true });
+    return true;
+  }
+  return false;
+}

package/src/cli.mjs

@@ -1,8 +1,10 @@
 import { execSync } from 'node:child_process';
 import { fetchFrames, fetchCharacter } from './api.mjs';
-import { playAnimation, playCompanion, showFrame } from './player.mjs';
+import { playAnimation, playCompanion, playReactiveCompanion, showFrame } from './player.mjs';
 import { browse } from './browse.mjs';
 import { startMcpServer } from './mcp.mjs';
+import { loadAnimations, clearCache } from './cache.mjs';
+import { installHooks, uninstallHooks } from './hooks.mjs';
 
 const HELP = `
   storymode-cli — play AI-animated pixel art in your terminal
@@ -13,12 +15,15 @@ const HELP = `
     storymode show <gallery_id>         Show first frame as static portrait
     storymode browse                    Browse the gallery interactively
     storymode mcp                       Start MCP server (for Claude Code)
+    storymode hooks install [--global]  Install Claude Code hooks
+    storymode hooks uninstall [--global] Remove Claude Code hooks
+    storymode cache clear [gallery_id]  Clear animation cache
 
   Options:
-    --sextant   Use sextant rendering (2x3 sub-pixels, sharper but needs
-                a modern terminal). Works with play, companion, show.
+    --sextant    Use sextant rendering (sharper, needs modern terminal).
     --size=compact|tiny   Size for companion mode (default: compact).
-    --detach    Return control immediately (companion mode).
+    --reactive   Enable reactive mode (responds to Claude Code events).
+    --detach     Return control immediately (companion mode).
 
   Controls (during playback):
     space     pause / resume
@@ -69,20 +74,32 @@ export async function run(args) {
 
     case 'companion': {
       if (!id) {
-        console.error('Usage: storymode companion <gallery_id> [--detach] [--size=compact|tiny]');
+        console.error('Usage: storymode companion <gallery_id> [--reactive] [--detach] [--size=full|compact|tiny]');
         process.exit(1);
       }
       const size = flags.size || 'compact';
       const detach = !!flags.detach;
-      const paneWidth = size === 'tiny' ? 14 : 22;
+      const reactive = !!flags.reactive;
+      const paneWidth = size === 'full' ? 62 : size === 'tiny' ? 14 : 22;
 
       // If we're already the companion pane (spawned by tmux split), play inline
       if (process.env.STORYMODE_COMPANION === '1') {
         try {
-          const fetchOpts = { size };
-          if (flags.sextant) fetchOpts.mode = 'sextant';
-          const framesData = await fetchFrames(id, fetchOpts);
-          await playCompanion(framesData);
+          if (reactive) {
+            // Reactive mode: load all animations, start socket server
+            const fetchOpts = { size };
+            if (flags.sextant) fetchOpts.mode = 'sextant';
+            const { animMap, character } = await loadAnimations(id, fetchOpts);
+            await playReactiveCompanion(animMap, {
+              characterName: character?.name || `#${id}`,
+              fullscreen: size === 'full',
+            });
+          } else {
+            const fetchOpts = { size };
+            if (flags.sextant) fetchOpts.mode = 'sextant';
+            const framesData = await fetchFrames(id, fetchOpts);
+            await playCompanion(framesData);
+          }
         } catch (err) {
           console.error(`Error: ${err.message}`);
           process.exit(1);
@@ -90,10 +107,16 @@ export async function run(args) {
         break;
       }
 
+      // Auto-install hooks when reactive mode is used
+      if (reactive) {
+        installHooks({ global: true });
+      }
+
       // Otherwise, open a tmux side pane
       const inTmux = !!process.env.TMUX;
       const sextantFlag = flags.sextant ? ' --sextant' : '';
-      const companionCmd = `STORYMODE_COMPANION=1 npx storymode-cli companion ${id} --size=${size}${sextantFlag}`;
+      const reactiveFlag = reactive ? ' --reactive' : '';
+      const companionCmd = `STORYMODE_COMPANION=1 npx storymode-cli companion ${id} --size=${size}${sextantFlag}${reactiveFlag}`;
 
       try {
         if (inTmux) {
@@ -103,7 +126,7 @@ export async function run(args) {
             { stdio: 'ignore' }
           );
           if (!detach) {
-            process.stderr.write(`  Companion sprite opened in side pane (${size}).\n`);
+            process.stderr.write(`  Companion sprite opened in side pane (${size}${reactive ? ', reactive' : ''}).\n`);
             process.stderr.write('  Close the pane or press q in it to stop.\n');
           }
         } else {
@@ -168,6 +191,37 @@ export async function run(args) {
       startMcpServer();
       break;
 
+    case 'hooks': {
+      const subcmd = positional[0];
+      const global = !!flags.global;
+      if (subcmd === 'install') {
+        installHooks({ global });
+      } else if (subcmd === 'uninstall') {
+        uninstallHooks({ global });
+      } else {
+        console.error('Usage: storymode hooks install|uninstall [--global]');
+        process.exit(1);
+      }
+      break;
+    }
+
+    case 'cache': {
+      const subcmd = positional[0];
+      if (subcmd === 'clear') {
+        const galleryId = positional[1];
+        const cleared = clearCache(galleryId);
+        if (cleared) {
+          console.log(`  Cache cleared${galleryId ? ` for gallery ${galleryId}` : ' (all)'}.\n`);
+        } else {
+          console.log('  No cache found.\n');
+        }
+      } else {
+        console.error('Usage: storymode cache clear [gallery_id]');
+        process.exit(1);
+      }
+      break;
+    }
+
     case '--help':
     case '-h':
     case 'help':

package/src/hook.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * Lightweight hook forwarder for Claude Code hooks.
+ * Reads STORYMODE_HOOK_EVENT env var + stdin JSON, sends to companion socket.
+ * Always exits 0 — must never block Claude Code.
+ */
+import { connect } from 'node:net';
+import { readdirSync } from 'node:fs';
+
+const event = process.env.STORYMODE_HOOK_EVENT;
+if (!event) process.exit(0);
+
+// Find the companion socket in /tmp
+function findSocket() {
+  try {
+    const files = readdirSync('/tmp');
+    const sock = files.find(f => f.startsWith('storymode-companion-') && f.endsWith('.sock'));
+    return sock ? `/tmp/${sock}` : null;
+  } catch {
+    return null;
+  }
+}
+
+// Read stdin (Claude Code passes hook context as JSON on stdin)
+let stdinData = '';
+process.stdin.setEncoding('utf-8');
+process.stdin.on('data', (chunk) => { stdinData += chunk; });
+
+// Use a 1s safety timeout — must not hang
+const timeout = setTimeout(() => process.exit(0), 1000);
+
+process.stdin.on('end', () => {
+  const sockPath = findSocket();
+  if (!sockPath) {
+    clearTimeout(timeout);
+    process.exit(0);
+  }
+
+  let parsed = {};
+  try {
+    parsed = JSON.parse(stdinData);
+  } catch {
+    // No valid JSON on stdin — that's fine for some events
+  }
+
+  const payload = JSON.stringify({ event, ...parsed }) + '\n';
+
+  const client = connect(sockPath, () => {
+    client.write(payload);
+    client.end();
+  });
+
+  client.on('close', () => {
+    clearTimeout(timeout);
+    process.exit(0);
+  });
+
+  client.on('error', () => {
+    // Companion not running — that's fine
+    clearTimeout(timeout);
+    process.exit(0);
+  });
+});
+
+// If stdin is already closed (no piped data), trigger 'end' manually
+if (process.stdin.readableEnded) {
+  process.stdin.emit('end');
+} else {
+  process.stdin.resume();
+}

package/src/hooks.mjs

@@ -0,0 +1,150 @@
+/**
+ * Hook installer/uninstaller for Claude Code.
+ * Merges storymode hook entries into Claude's settings.json.
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+// Resolve absolute path to hook.mjs
+const __filename = fileURLToPath(import.meta.url);
+const HOOK_SCRIPT = join(dirname(__filename), 'hook.mjs');
+
+function getSettingsPath(global) {
+  if (global) {
+    return join(homedir(), '.claude', 'settings.json');
+  }
+  return join(process.cwd(), '.claude', 'settings.json');
+}
+
+function makeHookEntry(eventName) {
+  return {
+    type: 'command',
+    command: `STORYMODE_HOOK_EVENT=${eventName} node "${HOOK_SCRIPT}"`,
+  };
+}
+
+/**
+ * The hook configuration we want to merge into settings.
+ * Uses PostToolUse matchers for action vs research distinction.
+ */
+function getStorymodeHooks() {
+  return {
+    SessionStart: [
+      { hooks: [makeHookEntry('SessionStart')] },
+    ],
+    UserPromptSubmit: [
+      { hooks: [makeHookEntry('UserPromptSubmit')] },
+    ],
+    PostToolUse: [
+      { matcher: 'Bash|Edit|Write', hooks: [makeHookEntry('PostToolUse_action')] },
+      { matcher: 'Read|Grep|Glob', hooks: [makeHookEntry('PostToolUse_research')] },
+    ],
+    PostToolUseFailure: [
+      { hooks: [makeHookEntry('PostToolUseFailure')] },
+    ],
+    Stop: [
+      { hooks: [makeHookEntry('Stop')] },
+    ],
+    SessionEnd: [
+      { hooks: [makeHookEntry('SessionEnd')] },
+    ],
+    SubagentStart: [
+      { hooks: [makeHookEntry('SubagentStart')] },
+    ],
+    SubagentStop: [
+      { hooks: [makeHookEntry('SubagentStop')] },
+    ],
+  };
+}
+
+/** Check if a hook entry is one of ours (by command prefix) */
+function isStorymodeHook(entry) {
+  if (entry.type !== 'command') return false;
+  return entry.command.includes('STORYMODE_HOOK_EVENT=');
+}
+
+/** Check if a hook group is one of ours */
+function isStorymodeGroup(group) {
+  return group.hooks?.some(isStorymodeHook);
+}
+
+export function installHooks({ global = false } = {}) {
+  const settingsPath = getSettingsPath(global);
+  let settings = {};
+
+  if (existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+    } catch {
+      console.error(`  Error reading ${settingsPath}`);
+      process.exit(1);
+    }
+  }
+
+  if (!settings.hooks) settings.hooks = {};
+
+  const newHooks = getStorymodeHooks();
+
+  for (const [eventName, groups] of Object.entries(newHooks)) {
+    if (!settings.hooks[eventName]) {
+      settings.hooks[eventName] = [];
+    }
+    // Remove any existing storymode entries
+    settings.hooks[eventName] = settings.hooks[eventName].filter(g => !isStorymodeGroup(g));
+    // Add our entries
+    settings.hooks[eventName].push(...groups);
+  }
+
+  mkdirSync(dirname(settingsPath), { recursive: true });
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+
+  const scope = global ? 'global' : 'project';
+  console.log(`  Storymode hooks installed (${scope}): ${settingsPath}`);
+  console.log(`  Hook script: ${HOOK_SCRIPT}`);
+  console.log(`  Events: ${Object.keys(newHooks).join(', ')}`);
+}
+
+export function uninstallHooks({ global = false } = {}) {
+  const settingsPath = getSettingsPath(global);
+
+  if (!existsSync(settingsPath)) {
+    console.log('  No settings file found — nothing to uninstall.');
+    return;
+  }
+
+  let settings;
+  try {
+    settings = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+  } catch {
+    console.error(`  Error reading ${settingsPath}`);
+    process.exit(1);
+  }
+
+  if (!settings.hooks) {
+    console.log('  No hooks configured — nothing to uninstall.');
+    return;
+  }
+
+  let removed = 0;
+  for (const eventName of Object.keys(settings.hooks)) {
+    const before = settings.hooks[eventName].length;
+    settings.hooks[eventName] = settings.hooks[eventName].filter(g => !isStorymodeGroup(g));
+    removed += before - settings.hooks[eventName].length;
+    // Clean up empty arrays
+    if (settings.hooks[eventName].length === 0) {
+      delete settings.hooks[eventName];
+    }
+  }
+
+  // Clean up empty hooks object
+  if (Object.keys(settings.hooks).length === 0) {
+    delete settings.hooks;
+  }
+
+  writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+
+  const scope = global ? 'global' : 'project';
+  console.log(`  Removed ${removed} storymode hook entries (${scope}): ${settingsPath}`);
+}

package/src/mcp.mjs

@@ -4,72 +4,122 @@ import { fetchGallery, fetchFrames, fetchCharacter } from './api.mjs';
 const TOOLS = [
   {
     name: 'list_characters',
-    description: 'List all characters in the Storymode gallery',
+    description: 'List all characters in the Storymode gallery with their available animations',
     inputSchema: { type: 'object', properties: {} },
   },
   {
     name: 'show_character',
-    description: 'Show character info and portrait (first frame as ANSI art)',
+    description: 'Show character info, portrait, and list of available animations. Use this to see what a character looks like and what animations they have.',
     inputSchema: {
       type: 'object',
-      properties: { gallery_id: { type: 'string', description: 'Gallery item ID' } },
+      properties: {
+        gallery_id: { type: 'string', description: 'Gallery item ID' },
+        animation: { type: 'string', description: 'Animation name to show a frame from (e.g. "waving hello", "casting lightning spell"). If omitted, shows the default animation.' },
+      },
       required: ['gallery_id'],
     },
   },
   {
     name: 'play_animation',
-    description: 'Get animation data for a gallery character (returns first frame as ANSI art + metadata)',
+    description: 'Show a frame from a specific animation and provide the CLI command to play it. Choose the animation contextually — "waving hello" for greetings, "thinking" for processing, "casting lightning spell" for impressive actions, "idle breathing" for ambient.',
     inputSchema: {
       type: 'object',
-      properties: { gallery_id: { type: 'string', description: 'Gallery item ID' } },
+      properties: {
+        gallery_id: { type: 'string', description: 'Gallery item ID' },
+        animation: { type: 'string', description: 'Animation name (e.g. "waving hello", "idle breathing"). Use list_characters or show_character to see available animations.' },
+      },
       required: ['gallery_id'],
     },
   },
 ];
 
+function findAnimation(animations, query) {
+  if (!query || !animations?.length) return null;
+  const q = query.toLowerCase();
+  // Exact match first
+  const exact = animations.find(a => (a.name || a.prompt || '').toLowerCase() === q);
+  if (exact) return exact;
+  // Partial match
+  const partial = animations.find(a => (a.name || a.prompt || '').toLowerCase().includes(q));
+  return partial || null;
+}
+
 async function handleToolCall(name, args) {
   switch (name) {
     case 'list_characters': {
       const items = await fetchGallery();
-      const lines = items.map((item, i) =>
-        `${i + 1}. ${item.name || 'untitled'}${item.prompt ? ' — ' + item.prompt : ''} (id: ${item.id})`
-      );
-      return lines.join('\n') || 'Gallery is empty.';
+      if (!items.length) return 'Gallery is empty.';
+      const parts = [];
+      for (const item of items) {
+        const char = await fetchCharacter(item.id).catch(() => null);
+        let line = `${item.name || 'untitled'} (id: ${item.id})`;
+        if (char?.backstory) line += `\n  ${char.backstory}`;
+        if (char?.animations?.length) {
+          const names = char.animations.map(a => a.name || a.prompt).join(', ');
+          line += `\n  Animations: ${names}`;
+        }
+        parts.push(line);
+      }
+      return parts.join('\n\n');
     }
     case 'show_character': {
       const id = args.gallery_id;
-      const [character, framesData] = await Promise.all([
-        fetchCharacter(id).catch(() => null),
-        fetchFrames(id, { size: 'tiny' }),
-      ]);
+      const character = await fetchCharacter(id).catch(() => null);
+
+      // Determine which animation to show
+      const fetchOpts = { size: 'tiny' };
+      if (args.animation && character?.animations?.length) {
+        const match = findAnimation(character.animations, args.animation);
+        if (match) fetchOpts.animId = match.id;
+      }
+      const framesData = await fetchFrames(id, fetchOpts);
+
       let text = '';
       if (character) {
         text += `Name: ${character.name || 'untitled'}\n`;
         if (character.backstory) text += `Backstory: ${character.backstory}\n`;
         if (character.animations?.length) {
-          text += `Animations: ${character.animations.map(a => a.name || a.prompt).join(', ')}\n`;
+          text += `\nAnimations (${character.animations.length}):\n`;
+          for (const a of character.animations) {
+            text += `  • ${a.name || a.prompt}\n`;
+          }
         }
         text += '\n';
       }
-      // First frame as ANSI
       if (framesData.frames?.length > 0) {
-        text += 'Portrait (ANSI):\n';
+        const label = args.animation || 'portrait';
+        text += `${label} (ANSI):\n`;
         text += framesData.frames[0].join('\n');
       }
       return text;
     }
     case 'play_animation': {
       const id = args.gallery_id;
-      const framesData = await fetchFrames(id, { size: 'tiny' });
-      let text = '';
-      if (framesData.frames?.length > 0) {
-        text += framesData.frames[0].join('\n');
-        text += `\n\n${framesData.frames.length} frames @ ${framesData.fps || 16} fps`;
-        text += `\n\nTo see the full animation, run:\n  npx storymode-cli play ${id}`;
-        text += `\n\nTo play as a companion sprite alongside your session:\n  npx storymode-cli companion ${id}`;
-      } else {
-        text = 'No frames available.';
+
+      // Look up animation ID by name
+      const fetchOpts = { size: 'tiny' };
+      let animLabel = 'default';
+      if (args.animation) {
+        const character = await fetchCharacter(id).catch(() => null);
+        if (character?.animations?.length) {
+          const match = findAnimation(character.animations, args.animation);
+          if (match) {
+            fetchOpts.animId = match.id;
+            animLabel = match.name || match.prompt;
+          } else {
+            const names = character.animations.map(a => a.name || a.prompt).join(', ');
+            return `Animation "${args.animation}" not found. Available: ${names}`;
+          }
+        }
       }
+
+      const framesData = await fetchFrames(id, fetchOpts);
+      if (!framesData.frames?.length) return 'No frames available.';
+
+      let text = framesData.frames[0].join('\n');
+      text += `\n\n"${animLabel}" — ${framesData.frames.length} frames @ ${framesData.fps || 16} fps`;
+      text += `\n\nTo see the full animation, run:\n  npx storymode-cli play ${id}`;
+      text += `\n\nTo play as a companion sprite alongside your session:\n  npx storymode-cli companion ${id}`;
       return text;
     }
     default:
@@ -92,7 +142,7 @@ function handleMessage(msg) {
         result: {
           protocolVersion: '2024-11-05',
           capabilities: { tools: {} },
-          serverInfo: { name: 'storymode', version: '1.0.0' },
+          serverInfo: { name: 'storymode', version: '1.1.2' },
         },
       });
       break;

package/src/player.mjs

@@ -1,3 +1,7 @@
+import { createServer } from 'node:net';
+import { unlinkSync, existsSync } from 'node:fs';
+import { mapEventToAnimation, pickSpeech, ONE_SHOT_ANIMS, IDLE_ANIM, SLEEP_ANIM, SLEEP_TIMEOUT_S, narrateEvent, SessionContext } from './reactive.mjs';
+
 const { stdout, stdin } = process;
 
 export function playAnimation(framesData) {
@@ -201,6 +205,314 @@ export function playCompanion(framesData) {
   });
 }
 
+/**
+ * Reactive companion player — responds to Claude Code events via Unix socket.
+ *
+ * @param {Map<string, {fps: number, frames: string[][]}>} animMap - All animations keyed by name
+ * @param {object} [opts]
+ * @param {string} [opts.characterName] - Character name for status display
+ * @param {boolean} [opts.fullscreen] - Use alt screen (full-screen mode)
+ */
+export function playReactiveCompanion(animMap, opts = {}) {
+  const characterName = opts.characterName || 'companion';
+  const fullscreen = !!opts.fullscreen;
+
+  // Find idle animation (required)
+  const idleData = animMap.get(IDLE_ANIM);
+  if (!idleData || idleData.frames.length === 0) {
+    console.log('No idle animation found. Need "idle breathing" animation.');
+    return Promise.resolve();
+  }
+
+  // Calculate maxLines across ALL animations for stable layout
+  let maxLines = 0;
+  for (const [, data] of animMap) {
+    for (const frame of data.frames) {
+      if (frame.length > maxLines) maxLines = frame.length;
+    }
+  }
+
+  // Speech bubble: max 3 lines + border (top + bottom) + blank line = 6 extra lines
+  const SPEECH_CLEAR_MS = 6000;
+  const BUBBLE_MAX_LINES = 3;
+  const bubbleLines = BUBBLE_MAX_LINES + 3; // top border + text lines + bottom border
+
+  // Status line + quit hint + speech bubble area
+  const totalLines = maxLines + 1 + bubbleLines;
+
+  // Animation state
+  let currentAnimName = IDLE_ANIM;
+  let currentFrames = idleData.frames;
+  let currentFps = idleData.fps || 16;
+  let frameIdx = 0;
+  let loopCount = 0;
+  let oneShotLoopsRemaining = 0; // >0 means playing a one-shot
+  let quit = false;
+
+  // Sleep state
+  let lastEventTime = Date.now();
+  let sleeping = false;
+
+  // Speech bubble state
+  let speechText = null;
+  let speechSetAt = 0;
+  let lastSpeech = null;
+
+  // Recent animation tracking (avoid repeats)
+  const recentAnims = [];
+
+  // Session context (for Phase 2 narrator)
+  const sessionCtx = new SessionContext();
+
+  // Socket path
+  const sockPath = `/tmp/storymode-companion-${process.pid}.sock`;
+
+  // Clean up stale socket
+  if (existsSync(sockPath)) {
+    try { unlinkSync(sockPath); } catch { /* ignore */ }
+  }
+
+  // --- Terminal setup ---
+  if (fullscreen) {
+    // Alt screen, hide cursor, clear
+    stdout.write('\x1b[?1049h\x1b[?25l\x1b[2J\x1b[H');
+  } else {
+    stdout.write('\x1b[?25l'); // hide cursor
+    // Reserve space
+    for (let i = 0; i < totalLines; i++) {
+      stdout.write('\n');
+    }
+    stdout.write(`\x1b[${totalLines}A`);
+    stdout.write('\x1b7'); // save cursor position
+  }
+
+  function switchAnimation(animName, type) {
+    if (!animMap.has(animName)) {
+      // Fallback to idle if animation not found
+      if (animName === IDLE_ANIM) return;
+      animName = IDLE_ANIM;
+      type = 'loop';
+    }
+
+    const data = animMap.get(animName);
+    currentAnimName = animName;
+    currentFrames = data.frames;
+    currentFps = data.fps || 16;
+    frameIdx = 0;
+    loopCount = 0;
+
+    if (type === 'one-shot' || ONE_SHOT_ANIMS.has(animName)) {
+      oneShotLoopsRemaining = 2; // play 2 loops for one-shot
+    } else {
+      oneShotLoopsRemaining = 0;
+    }
+
+    // Track recent
+    recentAnims.push(animName);
+    if (recentAnims.length > 3) recentAnims.shift();
+  }
+
+  /** Word-wrap text to fit inside a bubble of given inner width */
+  function wrapText(text, width) {
+    const words = text.split(' ');
+    const lines = [];
+    let line = '';
+    for (const word of words) {
+      if (line.length + word.length + (line ? 1 : 0) > width) {
+        if (line) lines.push(line);
+        line = word.slice(0, width); // truncate long words
+      } else {
+        line = line ? line + ' ' + word : word;
+      }
+    }
+    if (line) lines.push(line);
+    return lines.slice(0, BUBBLE_MAX_LINES);
+  }
+
+  /** Render a speech bubble as an array of strings */
+  function renderBubble(text, width) {
+    const innerW = width - 4; // │ + space + text + space + │
+    const wrapped = wrapText(text, innerW);
+    const lines = [];
+    lines.push('  \x1b[0m╭' + '─'.repeat(innerW + 2) + '╮');
+    for (const wl of wrapped) {
+      lines.push('  \x1b[0m│ ' + wl + ' '.repeat(innerW - wl.length) + ' │');
+    }
+    // Pad remaining bubble lines if fewer than max
+    for (let i = wrapped.length; i < BUBBLE_MAX_LINES; i++) {
+      lines.push('  \x1b[0m│' + ' '.repeat(innerW + 2) + '│');
+    }
+    lines.push('  \x1b[0m╰' + '─'.repeat(innerW + 2) + '╯');
+    return lines;
+  }
+
+  // Estimate sprite width from first frame of idle animation
+  const spriteWidth = (() => {
+    const firstLine = idleData.frames[0]?.[0] || '';
+    // Strip ANSI escape sequences to get visible character count
+    return firstLine.replace(/\x1b\[[0-9;]*m/g, '').length;
+  })();
+  const bubbleWidth = Math.max(20, Math.min(spriteWidth, 60));
+
+  function drawFrame(idx) {
+    let out = fullscreen ? '\x1b[H' : '\x1b8'; // cursor home vs restore
+    const frameLines = currentFrames[idx] || [];
+    for (let i = 0; i < maxLines; i++) {
+      if (i < frameLines.length) {
+        out += frameLines[i];
+      }
+      out += '\x1b[K\n';
+    }
+
+    // Auto-clear speech after timeout
+    if (speechText && (Date.now() - speechSetAt > SPEECH_CLEAR_MS)) {
+      speechText = null;
+    }
+
+    // Speech bubble or empty space
+    if (speechText) {
+      const bubble = renderBubble(speechText, bubbleWidth);
+      for (const bl of bubble) {
+        out += bl + '\x1b[K\n';
+      }
+    } else {
+      // Empty lines to keep layout stable
+      for (let i = 0; i < bubbleLines - 1; i++) {
+        out += '\x1b[K\n';
+      }
+    }
+
+    // Status line
+    out += `\x1b[0m\x1b[K  ${characterName} [${currentAnimName}]  [q]=quit\n`;
+    stdout.write(out);
+  }
+
+  // --- Socket server ---
+  const server = createServer((conn) => {
+    let buf = '';
+    conn.on('data', (chunk) => { buf += chunk.toString(); });
+    conn.on('end', () => {
+      // Process each line (usually just one)
+      for (const line of buf.split('\n').filter(Boolean)) {
+        try {
+          const msg = JSON.parse(line);
+          handleEvent(msg);
+        } catch {
+          // Ignore malformed messages
+        }
+      }
+    });
+  });
+
+  server.on('error', (err) => {
+    // If socket already in use, try to recover
+    if (err.code === 'EADDRINUSE') {
+      try { unlinkSync(sockPath); } catch { /* ignore */ }
+      server.listen(sockPath);
+    }
+  });
+
+  server.listen(sockPath);
+
+  function handleEvent(msg) {
+    lastEventTime = Date.now();
+    sleeping = false;
+
+    // Update session context
+    sessionCtx.update(msg);
+
+    // Instant layer: static map
+    const mapping = mapEventToAnimation(msg.event, animMap);
+    if (mapping) {
+      switchAnimation(mapping.anim, mapping.type);
+    }
+
+    // Speech bubble
+    const speech = pickSpeech(msg.event, lastSpeech);
+    if (speech) {
+      speechText = speech;
+      speechSetAt = Date.now();
+      lastSpeech = speech;
+    }
+  }
+
+  function cleanup() {
+    if (stdin.isTTY) stdin.setRawMode(false);
+    stdin.removeAllListeners('data');
+    stdin.pause();
+    if (fullscreen) {
+      stdout.write('\x1b[?1049l\x1b[?25h'); // exit alt screen, show cursor
+    } else {
+      stdout.write('\x1b[?25h'); // show cursor
+    }
+    server.close();
+    try { unlinkSync(sockPath); } catch { /* ignore */ }
+  }
+
+  function handleKey(data) {
+    const key = data.toString();
+    if (key === 'q' || key === '\x03') {
+      quit = true;
+    }
+  }
+
+  if (stdin.isTTY) {
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.on('data', handleKey);
+  }
+
+  return new Promise((resolve) => {
+    const interval = () => 1000 / currentFps;
+
+    function tick() {
+      if (quit) {
+        cleanup();
+        resolve();
+        return;
+      }
+
+      // Check for sleep
+      const idleTime = (Date.now() - lastEventTime) / 1000;
+      if (idleTime >= SLEEP_TIMEOUT_S && !sleeping) {
+        sleeping = true;
+        if (animMap.has(SLEEP_ANIM)) {
+          switchAnimation(SLEEP_ANIM, 'loop');
+        }
+      }
+
+      drawFrame(frameIdx);
+      frameIdx++;
+
+      if (frameIdx >= currentFrames.length) {
+        loopCount++;
+        frameIdx = 0;
+
+        // One-shot: count down loops, return to idle
+        if (oneShotLoopsRemaining > 0) {
+          oneShotLoopsRemaining--;
+          if (oneShotLoopsRemaining <= 0) {
+            switchAnimation(IDLE_ANIM, 'loop');
+          }
+        }
+      }
+
+      setTimeout(tick, interval());
+    }
+
+    tick();
+
+    // Print socket path so hooks can find it
+    process.stderr.write(`  Socket: ${sockPath}\n`);
+    process.stderr.write(`  Listening for Claude Code events...\n`);
+
+    const sigHandler = () => { quit = true; };
+    process.on('SIGINT', sigHandler);
+    process.on('SIGTERM', sigHandler);
+    process.on('SIGHUP', sigHandler);
+  });
+}
+
 export function showFrame(framesData, info) {
   const frames = framesData.frames;
   if (!frames || frames.length === 0) {

package/src/reactive.mjs

@@ -0,0 +1,176 @@
+/**
+ * Reactive companion: event mapping, narrator, animation loader.
+ * Phase 1 — static map only (no LLM).
+ */
+
+/** Animations that play once then return to idle */
+export const ONE_SHOT_ANIMS = new Set([
+  'waving hello',
+]);
+
+/** Default idle animation name */
+export const IDLE_ANIM = 'idle breathing';
+
+/** Sleep animation name */
+export const SLEEP_ANIM = 'falling asleep';
+
+/** Seconds of inactivity before sleep */
+export const SLEEP_TIMEOUT_S = 120;
+
+/**
+ * Static map: hook event → animation name + type.
+ * Key format matches STORYMODE_HOOK_EVENT env var values.
+ */
+export const STATIC_MAP = {
+  SessionStart:           { anim: 'waving hello',                    type: 'one-shot' },
+  UserPromptSubmit:       { anim: 'scratching head while thinking',  type: 'loop' },
+  PostToolUse_action:     { anim: 'casting lightning spell',         type: 'loop' },
+  PostToolUse_research:   { anim: 'scratching head while thinking',  type: 'loop' },
+  PostToolUseFailure:     { anim: 'charging up magical energy',      type: 'loop' },
+  Stop:                   { anim: 'idle breathing',                  type: 'loop' },
+  SessionEnd:             { anim: 'waving hello',                    type: 'one-shot' },
+  SubagentStart:          { anim: 'charging up magical energy',      type: 'one-shot' },
+  SubagentStop:           { anim: 'idle breathing',                  type: 'loop' },
+};
+
+/**
+ * Speech lines per event type. A random one is picked each time.
+ * null = no speech (stay quiet).
+ */
+export const SPEECH_MAP = {
+  SessionStart:         ['Hey there!', 'Ready to code!', "Let's go~", 'Hi hi!', 'Oh, hello!'],
+  UserPromptSubmit:     ['Hmm...', 'Interesting...', 'Ooh, a challenge!', 'Let me think...', null, null],
+  PostToolUse_action:   ['Nice!', 'Zap!', 'Code go brrr~', null, null, null],
+  PostToolUse_research: ['Looking...', 'Where is it...', null, null, null, null],
+  PostToolUseFailure:   ['Oof!', 'That stings...', "We'll fix it!", 'Ouch!', 'Ow ow ow'],
+  Stop:                 ['Done!', 'All yours~', null, null],
+  SessionEnd:           ['Bye bye!', 'See ya~', 'Good session!'],
+  SubagentStart:        ['Reinforcements!', 'A friend!', 'Backup arriving~'],
+  SubagentStop:         ['And they vanish...', 'Back to us~', null],
+};
+
+/** Pick a random speech line for an event, avoiding the last spoken line */
+export function pickSpeech(eventType, lastSpeech) {
+  const lines = SPEECH_MAP[eventType];
+  if (!lines || lines.length === 0) return null;
+  // Try up to 3 times to avoid repeating
+  for (let i = 0; i < 3; i++) {
+    const pick = lines[Math.floor(Math.random() * lines.length)];
+    if (pick !== lastSpeech) return pick;
+  }
+  return lines[Math.floor(Math.random() * lines.length)];
+}
+
+/**
+ * Instant-layer lookup: event string → { anim, type } or null.
+ * Falls back gracefully if the animation doesn't exist in the loaded set.
+ */
+export function mapEventToAnimation(eventType, availableAnims) {
+  const mapping = STATIC_MAP[eventType];
+  if (!mapping) return null;
+  // If the target animation isn't available, fall back to idle
+  if (availableAnims && !availableAnims.has(mapping.anim)) {
+    if (mapping.anim === IDLE_ANIM) return null; // already idle
+    return { anim: IDLE_ANIM, type: 'loop' };
+  }
+  return mapping;
+}
+
+/**
+ * Narrate a raw hook event into a 1-line human-readable summary.
+ * Used for future LLM context (Phase 2).
+ */
+export function narrateEvent(msg) {
+  const { event } = msg;
+
+  if (event === 'SessionStart') return 'Session started';
+  if (event === 'SessionEnd') return 'Session ended';
+  if (event === 'SubagentStart') return 'Sub-agent spawned';
+  if (event === 'SubagentStop') return 'Sub-agent finished';
+  if (event === 'Stop') return 'Claude stopped generating';
+
+  if (event === 'UserPromptSubmit') {
+    const prompt = msg.prompt || msg.tool_input?.prompt;
+    if (prompt) {
+      const short = prompt.length > 80 ? prompt.slice(0, 77) + '...' : prompt;
+      return `User asked: '${short}'`;
+    }
+    return 'User submitted a prompt';
+  }
+
+  if (event === 'PostToolUseFailure') {
+    const tool = msg.tool_name || msg.tool || 'unknown tool';
+    return `${tool} failed`;
+  }
+
+  // PostToolUse_action or PostToolUse_research
+  if (event?.startsWith('PostToolUse')) {
+    const tool = msg.tool_name || msg.tool || '';
+    const input = msg.tool_input || {};
+
+    if (tool === 'Bash') {
+      const cmd = input.command || '';
+      const short = cmd.length > 60 ? cmd.slice(0, 57) + '...' : cmd;
+      return `Ran \`${short}\``;
+    }
+    if (tool === 'Edit' || tool === 'Write') {
+      const file = (input.file_path || '').split('/').pop() || 'a file';
+      return `Edited ${file}`;
+    }
+    if (tool === 'Read') {
+      const file = (input.file_path || '').split('/').pop() || 'a file';
+      return `Read ${file}`;
+    }
+    if (tool === 'Grep') {
+      const pattern = input.pattern || '';
+      return `Searched for '${pattern}'`;
+    }
+    if (tool === 'Glob') {
+      const pattern = input.pattern || '';
+      return `Searched files: ${pattern}`;
+    }
+    return `Used ${tool}`;
+  }
+
+  return `Event: ${event || 'unknown'}`;
+}
+
+/**
+ * Session context — tracks accumulated stats for LLM context (Phase 2).
+ */
+export class SessionContext {
+  constructor() {
+    this.startedAt = Date.now();
+    this.toolCount = 0;
+    this.errorCount = 0;
+    this.filesTouched = new Set();
+    this.currentActivity = 'idle';
+  }
+
+  update(msg) {
+    const { event } = msg;
+    if (event?.startsWith('PostToolUse')) {
+      this.toolCount++;
+      const file = msg.tool_input?.file_path;
+      if (file) this.filesTouched.add(file.split('/').pop());
+      this.currentActivity = event.includes('research') ? 'researching' : 'coding';
+    }
+    if (event === 'PostToolUseFailure') {
+      this.errorCount++;
+      this.currentActivity = 'debugging';
+    }
+    if (event === 'UserPromptSubmit') {
+      this.currentActivity = 'thinking';
+    }
+  }
+
+  toJSON() {
+    return {
+      duration_s: Math.round((Date.now() - this.startedAt) / 1000),
+      tool_count: this.toolCount,
+      error_count: this.errorCount,
+      files_touched: [...this.filesTouched].slice(-10),
+      current_activity: this.currentActivity,
+    };
+  }
+}