storymode-cli 1.1.2 → 1.2.1

package/README.md

@@ -1,64 +1,60 @@
 # storymode-cli
 
-Play AI-animated pixel art characters in your terminal.
+AI-animated pixel art companions for your terminal. Reacts to Claude Code in real time.
 
 ```
-npx storymode-cli play 1
+npx storymode-cli play 3
 ```
 
-## Commands
+## Quick Start
 
-### `play <id>`
-Play a gallery animation with interactive controls.
+```bash
+# Browse available characters
+npx storymode-cli browse
 
-```
-npx storymode-cli play 1
+# Run a companion alongside Claude Code
+npx storymode-cli play 3
 ```
 
-**Controls:**
-- `space` — pause / resume
-- `←` `→` — step frames (when paused)
-- `+` `-` — adjust speed
-- `q` — quit
+The companion opens in a tmux side pane and reacts to what Claude Code is doing — switching animations when it reads files, writes code, hits errors, etc. Speech bubbles show in-character lines.
 
-### `show <id>`
-Print the first frame as a static portrait.
+## Options
 
-```
-npx storymode-cli show 1
+```bash
+npx storymode-cli play 3              # full size (default)
+npx storymode-cli play 3 --compact    # smaller pane
+npx storymode-cli play 3 --tiny       # tiny pane
+npx storymode-cli play 3 --no-ai      # disable AI personality
+npx storymode-cli play 3 --classic    # full-screen animation viewer
 ```
 
-### `browse`
-Browse the gallery and pick an animation to play.
+**Keyboard:** `a` add API key (enables AI personality), `q` quit.
 
-```
-npx storymode-cli browse
-```
+## AI Personality
 
-### `mcp`
-Start a Model Context Protocol server for Claude Code integration.
+On first launch, you'll be prompted for an `ANTHROPIC_API_KEY`. This enables the companion to generate unique, in-character speech using Claude Haiku. The key is saved locally to `~/.storymode/config.json`.
 
-Add to `~/.claude/settings.json`:
+Without it, you still get reactive animations and preset speech lines.
 
-```json
-{
-  "mcpServers": {
-    "storymode": {
-      "command": "npx",
-      "args": ["storymode-cli", "mcp"]
-    }
-  }
-}
-```
+## How It Works
+
+Three layers, each faster than the last:
+
+1. **Instant** (0ms) — maps Claude Code events to animations + random speech lines
+2. **State engine** (0ms) — tracks character dimensions (energy, frustration, etc.) over time. Threshold crossings change animations (e.g. falls asleep when energy is low)
+3. **LLM personality** (~3s) — batches recent events and asks Haiku for an in-character reaction
+
+## Character Personalities
+
+Characters can have personality files that control their behavior. See [docs/personality.md](docs/personality.md) for the full guide.
 
 ## Requirements
 
 - Node.js 18+
-- A terminal with truecolor support (iTerm2, Terminal.app, Windows Terminal, Claude Code)
-
-## Zero Dependencies
+- Truecolor terminal (iTerm2, Terminal.app, Windows Terminal, Claude Code)
+- tmux (auto-installed if missing)
 
-Built entirely on Node.js built-ins — no `node_modules` needed.
+Zero runtime dependencies — built entirely on Node.js built-ins.
 
 ## Gallery
 

package/package.json

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

package/src/agent.mjs

@@ -0,0 +1,282 @@
+/**
+ * Character agent — local LLM-powered reactions via Anthropic API.
+ *
+ * Calls Claude Haiku directly from the CLI using the user's own API key.
+ * No session data is sent to the storymode server — only to Anthropic's API.
+ *
+ * Accumulates events in a 3-second debounce window, then fires one
+ * Haiku call. Returns {animation, speech, mood} or null on failure.
+ */
+
+import https from 'node:https';
+import { getApiKey } from './config.mjs';
+
+const DEBOUNCE_MS = 3000;
+const REQUEST_TIMEOUT_MS = 8000;
+const API_URL = 'https://api.anthropic.com/v1/messages';
+const DEFAULT_MODEL = 'claude-haiku-4-5-20251001';
+
+/**
+ * Recursively walk a soul/voice object into prompt text.
+ */
+function walkTree(obj, indent = '') {
+  if (typeof obj === 'string') return indent + obj;
+  if (Array.isArray(obj)) return obj.map(item => indent + '- ' + item).join('\n');
+  if (typeof obj === 'object' && obj !== null) {
+    return Object.entries(obj)
+      .map(([k, v]) => {
+        const label = k.replace(/_/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
+        const child = walkTree(v, indent + '  ');
+        if (typeof v === 'string') return `${indent}${label}: ${v}`;
+        return `${indent}${label}:\n${child}`;
+      })
+      .join('\n');
+  }
+  return String(obj);
+}
+
+/**
+ * Build system prompt from personality data + animation info.
+ *
+ * @param {object} character - { name, soul, voice, ... }
+ * @param {object} [disposition] - { drives, state }
+ * @param {Array<{name: string, meaning?: string}>} animEntries - Animation name + meaning pairs
+ */
+function buildSystemPrompt(character, disposition, animEntries) {
+  const name = character.name || 'Companion';
+  const parts = [`You are ${name}.`];
+
+  // Soul
+  if (character.soul) {
+    parts.push('\n== Soul ==');
+    parts.push(walkTree(character.soul));
+  } else if (character.backstory) {
+    parts.push('\n== Soul ==');
+    parts.push(`Backstory: ${character.backstory}`);
+  }
+
+  // Drives
+  if (disposition?.drives?.length) {
+    parts.push('\n== Behavioral tendencies ==');
+    for (const d of disposition.drives) {
+      parts.push(`- ${d}`);
+    }
+  }
+
+  // Voice
+  if (character.voice) {
+    parts.push('\n== Voice ==');
+    parts.push(walkTree(character.voice));
+  }
+
+  // Speech examples
+  if (character.speech?.examples?.length) {
+    parts.push('\n== Example lines ==');
+    for (const ex of character.speech.examples) {
+      parts.push(`"${ex}"`);
+    }
+  }
+
+  // Animations with meanings
+  parts.push('\n== Available animations ==');
+  for (const entry of animEntries) {
+    if (entry.meaning) {
+      parts.push(`- ${entry.name} (${entry.meaning})`);
+    } else {
+      parts.push(`- ${entry.name}`);
+    }
+  }
+
+  parts.push(`
+You are watching someone work. You sit beside their screen as an animated pixel art companion.
+
+Respond with JSON:
+{"animation": "<name>", "speech": "<short text or null>", "mood": "<word>"}
+
+Rules:
+- Stay in character. Your personality shines through HOW you react.
+- Keep speech SHORT (under 60 chars). You're a sprite, not a chatbot.
+- Set speech to null when you have nothing interesting to say (~40% of the time).
+- React to PATTERNS ("you've been at this a while") not just single events.
+- Don't be annoying. If the user is in flow, stay quiet and supportive.
+- Vary your reactions. Don't repeat the same phrase twice in a row.
+- Let your current state inform your mood and animation choices.`);
+
+  return parts.join('\n');
+}
+
+/**
+ * Call the Anthropic Messages API directly (no SDK, zero deps).
+ */
+function callLLM(apiKey, model, systemPrompt, userMessage) {
+  return new Promise((resolve, reject) => {
+    const body = JSON.stringify({
+      model,
+      max_tokens: 100,
+      temperature: 0.9,
+      system: [{ type: 'text', text: systemPrompt, cache_control: { type: 'ephemeral' } }],
+      messages: [{ role: 'user', content: userMessage }],
+    });
+
+    const req = https.request({
+      hostname: 'api.anthropic.com',
+      path: '/v1/messages',
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-api-key': apiKey,
+        'anthropic-version': '2023-06-01',
+        'Content-Length': Buffer.byteLength(body),
+      },
+      timeout: REQUEST_TIMEOUT_MS,
+    }, (res) => {
+      const chunks = [];
+      res.on('data', (c) => chunks.push(c));
+      res.on('end', () => {
+        if (res.statusCode !== 200) {
+          reject(new Error(`Anthropic API ${res.statusCode}`));
+          return;
+        }
+        try {
+          const data = JSON.parse(Buffer.concat(chunks).toString('utf-8'));
+          let text = data.content?.[0]?.text?.trim() || '';
+          // Strip markdown code fences
+          if (text.startsWith('```')) {
+            text = text.split('```')[1];
+            if (text.startsWith('json')) text = text.slice(4);
+            text = text.trim();
+          }
+          const result = JSON.parse(text);
+          if (!result.animation) result.animation = 'idle breathing';
+          if (!result.mood) result.mood = 'neutral';
+          if (result.speech === 'null' || result.speech === '') result.speech = null;
+          resolve(result);
+        } catch (e) {
+          reject(e);
+        }
+      });
+      res.on('error', reject);
+    });
+    req.on('error', reject);
+    req.on('timeout', () => { req.destroy(); reject(new Error('timeout')); });
+    req.write(body);
+    req.end();
+  });
+}
+
+/**
+ * Extract animation entries (name + meaning) from personality animations object.
+ * Falls back to plain name list if no personality animations provided.
+ */
+function extractAnimEntries(personalityAnims, animationNames) {
+  if (!personalityAnims) {
+    return animationNames.map(n => ({ name: n }));
+  }
+  const entries = [];
+  const seen = new Set();
+  for (const set of Object.values(personalityAnims)) {
+    for (const entry of Object.values(set)) {
+      if (entry.name && !seen.has(entry.name)) {
+        seen.add(entry.name);
+        entries.push({ name: entry.name, meaning: entry.meaning || undefined });
+      }
+    }
+  }
+  // Add any animation names from the loaded set that aren't in the personality file
+  for (const n of animationNames) {
+    if (!seen.has(n)) {
+      entries.push({ name: n });
+    }
+  }
+  return entries;
+}
+
+/**
+ * Create a debounced agent for a specific character.
+ *
+ * @param {object} personality - Full personality data { character, disposition, animations, speech }
+ *   Falls back to legacy format { name, backstory, ... } if no character sub-object
+ * @param {string[]} animationNames - Available animation names from loaded sprites
+ * @param {function} onReaction - Callback: ({animation, speech, mood}) => void
+ * @param {object} [opts]
+ * @param {string} [opts.model] - Anthropic model ID (default: claude-haiku-4-5-20251001)
+ * @param {function} [opts.getState] - Returns current state values as { energy: 0.42, ... }
+ * @returns {{ pushEvent(event, sessionContext), flush(sessionContext), destroy() } | null}
+ */
+export function createAgent(personality, animationNames, onReaction, opts = {}) {
+  const apiKey = getApiKey();
+  if (!apiKey) return null; // No API key — personality layer disabled
+
+  const model = opts.model || DEFAULT_MODEL;
+
+  const character = personality.soul || personality;
+  const disposition = personality.state || null;
+  const personalityAnims = personality.animations || null;
+
+  const animEntries = extractAnimEntries(personalityAnims, animationNames);
+  const systemPrompt = buildSystemPrompt(character, disposition, animEntries);
+
+  let buffer = [];
+  let timer = null;
+
+  function flush(sessionContext) {
+    if (buffer.length === 0) return;
+    const events = buffer.splice(0);
+    clearTimeout(timer);
+    timer = null;
+
+    // Build user message from events + context + current state
+    const parts = [];
+    if (sessionContext) {
+      parts.push(`Session: ${sessionContext.duration_s || 0}s, ` +
+        `${sessionContext.tool_count || 0} tools used, ` +
+        `${sessionContext.error_count || 0} errors, ` +
+        `activity: ${sessionContext.current_activity || 'unknown'}`);
+    }
+
+    // Inject current state values
+    if (opts.getState) {
+      const state = opts.getState();
+      if (state && Object.keys(state).length > 0) {
+        const stateStr = Object.entries(state)
+          .map(([k, v]) => `${k}: ${v}`)
+          .join('  ');
+        parts.push(`Current state: ${stateStr}`);
+      }
+    }
+
+    parts.push('Recent events:');
+    for (const ev of events) {
+      parts.push(`- ${ev.summary || ev.type || 'unknown'}`);
+    }
+
+    callLLM(apiKey, model, systemPrompt, parts.join('\n'))
+      .then((result) => {
+        if (result && (result.animation || result.speech)) {
+          onReaction(result);
+        }
+      })
+      .catch(() => {
+        // Graceful degradation — instant layer handles reactions
+      });
+  }
+
+  return {
+    pushEvent(event, sessionContext) {
+      buffer.push(event);
+      if (timer) clearTimeout(timer);
+      timer = setTimeout(() => flush(sessionContext), DEBOUNCE_MS);
+    },
+
+    flush(sessionContext) {
+      if (timer) clearTimeout(timer);
+      timer = null;
+      flush(sessionContext);
+    },
+
+    destroy() {
+      if (timer) clearTimeout(timer);
+      buffer = [];
+    },
+  };
+}

package/src/browse.mjs

@@ -2,6 +2,19 @@ import { createInterface } from 'node:readline/promises';
 import { fetchGallery, fetchFrames } from './api.mjs';
 import { playAnimation } from './player.mjs';
 
+const ANSI_RE = /\x1b\[[0-9;]*m/g;
+
+function visibleWidth(str) {
+  return str.replace(ANSI_RE, '').length;
+}
+
+/** Pad an ANSI string to a visible width, resetting color first */
+function padAnsi(str, width) {
+  const visible = visibleWidth(str);
+  if (visible >= width) return str + '\x1b[0m';
+  return str + '\x1b[0m' + ' '.repeat(width - visible);
+}
+
 export async function browse() {
   const spinner = startSpinner('Fetching gallery...');
   let items;
@@ -16,17 +29,88 @@ export async function browse() {
     return;
   }
 
+  // Fetch compact first-frame thumbnails in parallel
+  const spinner2 = startSpinner('Loading thumbnails...');
+  let thumbnails;
+  try {
+    thumbnails = await Promise.all(
+      items.map(async (item) => {
+        try {
+          const data = await fetchFrames(item.id, { size: 'compact' });
+          return data.frames?.[0] || null;
+        } catch {
+          return null;
+        }
+      })
+    );
+  } finally {
+    stopSpinner(spinner2);
+  }
+
+  // Check if any thumbnails loaded at all
+  const anyThumbs = thumbnails.some(t => t && t.length > 0);
+
   console.log('');
   console.log('  storymode gallery');
   console.log('');
-  for (let i = 0; i < items.length; i++) {
-    const item = items[i];
-    const name = item.name || 'untitled';
-    const prompt = item.prompt ? ` — ${item.prompt}` : '';
-    const author = item.author_name ? ` (by ${item.author_name})` : '';
-    console.log(`  ${String(i + 1).padStart(3)}.  ${name}${prompt}${author}`);
+
+  if (anyThumbs) {
+    // Measure sprite width from first available thumbnail
+    let spriteWidth = 0;
+    for (const thumb of thumbnails) {
+      if (thumb && thumb.length > 0) {
+        spriteWidth = Math.max(...thumb.map(l => visibleWidth(l)));
+        break;
+      }
+    }
+
+    const gap = 3;
+    const cellWidth = Math.max(spriteWidth, 16) + gap;
+    const termWidth = process.stdout.columns || 80;
+    const cols = Math.max(1, Math.floor(termWidth / cellWidth));
+
+    for (let row = 0; row < Math.ceil(items.length / cols); row++) {
+      const start = row * cols;
+      const rowItems = items.slice(start, start + cols);
+      const rowThumbs = thumbnails.slice(start, start + cols);
+
+      // Max sprite height in this row
+      const maxH = Math.max(...rowThumbs.map(t => t ? t.length : 0), 1);
+
+      // Render sprite lines side by side
+      for (let line = 0; line < maxH; line++) {
+        let out = '';
+        for (let col = 0; col < rowItems.length; col++) {
+          const frameLine = rowThumbs[col]?.[line] || '';
+          out += padAnsi(frameLine, cellWidth);
+        }
+        console.log(out);
+      }
+
+      // Label line below each sprite
+      let labelOut = '';
+      for (let col = 0; col < rowItems.length; col++) {
+        const idx = start + col;
+        const item = rowItems[col];
+        const name = item.name || 'untitled';
+        let label = `  ${String(idx + 1).padStart(2)}. ${name}`;
+        if (label.length > cellWidth - 1) label = label.slice(0, cellWidth - 2) + '…';
+        labelOut += label.padEnd(cellWidth);
+      }
+      console.log(labelOut);
+      console.log('');
+    }
+  } else {
+    // Fallback: text-only list if no thumbnails loaded
+    for (let i = 0; i < items.length; i++) {
+      const item = items[i];
+      const name = item.name || 'untitled';
+      const prompt = item.prompt ? ` — ${item.prompt}` : '';
+      const author = item.author_name ? ` (by ${item.author_name})` : '';
+      console.log(`  ${String(i + 1).padStart(3)}.  ${name}${prompt}${author}`);
+    }
+    console.log('');
   }
-  console.log('');
 
   const rl = createInterface({ input: process.stdin, output: process.stdout });
   try {

package/src/cache.mjs

@@ -0,0 +1,189 @@
+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;
+  }
+}
+
+/** Write personality.json to cache */
+export function writeCachePersonality(galleryId, personality, size) {
+  const dir = getCacheDir(galleryId, size);
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, 'personality.json'), JSON.stringify(personality));
+}
+
+/** Read cached personality.json */
+export function readCachedPersonality(galleryId, size) {
+  const file = join(getCacheDir(galleryId, size), 'personality.json');
+  if (!existsSync(file)) return null;
+  try {
+    return JSON.parse(readFileSync(file, 'utf-8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read personality.json from the characters directory.
+ * Path: ~/.storymode/characters/{id}/personality.json
+ */
+export function readLocalPersonality(galleryId) {
+  const file = join(STORYMODE_DIR, 'characters', String(galleryId), 'personality.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, personality }
+ *
+ * Personality loading priority:
+ *   1. ~/.storymode/characters/{id}/personality.json (user-authored)
+ *   2. Cached personality.json (from server, if it provides one)
+ *   3. null (no personality — instant + fallback sleep only)
+ */
+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);
+  }
+
+  // Load personality: local file > cached > null
+  const personality = readLocalPersonality(galleryId)
+    || readCachedPersonality(galleryId, size)
+    || null;
+
+  return { animMap, character, personality };
+}
+
+/** 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;
+}