cc-face 0.1.10

package/README.md

@@ -0,0 +1,102 @@
+# cc-face: Animated ASCII anime girl for Claude Code
+
+An expressive ASCII face that reacts to Claude Code in real-time. It monitors Claude's activity and changes expression based on what Claude is doing — idle, listening, thinking, or typing.
+
+## Install
+
+```bash
+npm i -g cc-face
+```
+
+Requires Node.js >= 18 and [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed.
+
+## Usage
+
+Run Claude Code in one terminal, and render the face in another.
+
+**Terminal 1** — launch Claude with the face server:
+```bash
+cc-face
+```
+
+**Terminal 2** — open the face renderer:
+```bash
+cc-face -face
+```
+
+The face automatically detects Claude's state:
+
+| Expression | Trigger |
+|---|---|
+| **Idle** | Claude is not active (relaxed blinking animation) |
+| **Listening** | You're typing a prompt |
+| **Thinking** | Claude is reasoning (spinner/thinking indicator detected) |
+| **Typing** | Claude is generating output |
+
+### Options
+
+| Flag | Description |
+|---|---|
+| `--face <path>` | Load a custom face definition |
+| `-face, -f` | Run only the face renderer |
+| `--theme dark\|light\|auto` | Color theme (default: `auto`) |
+| `--no-face` | Plain passthrough, no face server |
+| `--debug` | Print diagnostics before launching |
+| `-h, --help` | Show help |
+| `-v, --version` | Show version |
+
+### Environment variables
+
+| Variable | Description |
+|---|---|
+| `CLAUDE_PATH` | Override the path to the Claude binary |
+
+## How it works
+
+cc-face runs as two processes connected via a Unix domain socket:
+
+1. **Wrapper** (`cc-face`) — spawns Claude Code in a PTY, monitors the output stream for state changes (spinner characters, text output, etc.), and broadcasts state updates over IPC.
+2. **Renderer** (`cc-face -face`) — connects to the wrapper, receives state updates, and renders the appropriate animated ASCII frames with smooth per-character transitions.
+
+Each expression has 26-27 hand-drawn ASCII frames that loop with configurable timing. Transitions between expressions use a sigmoid-distributed per-character flip effect.
+
+## Custom faces
+
+Export a `FaceDefinition` from a TypeScript file:
+
+```ts
+import { FaceDefinition } from 'cc-face/src/types';
+
+const myFace: FaceDefinition = {
+  name: 'robot',
+  width: 16,
+  height: 5,
+  expressions: {
+    idle: { name: 'idle', frames: [{ art: [/* ... */] }] },
+    typing: { /* ... */ },
+    thinking: { /* ... */ },
+    listening: { /* ... */ },
+  },
+};
+
+export default myFace;
+```
+
+```bash
+cc-face --face ./my-face.ts
+```
+
+## Local development
+
+```bash
+npm install
+npm run build
+npm run dev                    # run wrapper (tsx bin/cli.ts)
+npm run dev -- -face           # run face renderer
+npm test                       # run tests once
+npm run test:watch             # run tests in watch mode
+```
+
+## License
+
+MIT

package/dist/bin/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/cli.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+import { run } from '../src/main.js';
+import { createRequire } from 'node:module';
+// ── Argument parsing ────────────────────────────────────────────────
+function parseArgs(argv) {
+    const options = {
+        theme: 'auto',
+        noFace: false,
+        displayOnly: false,
+        debug: false,
+        help: false,
+        version: false,
+    };
+    const args = argv.slice(2); // skip node and script path
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--help' || arg === '-h') {
+            options.help = true;
+            continue;
+        }
+        if (arg === '--version' || arg === '-v') {
+            options.version = true;
+            continue;
+        }
+        if (arg === '--no-face') {
+            options.noFace = true;
+            continue;
+        }
+        if (arg === '-display' || arg === '-f') {
+            options.displayOnly = true;
+            continue;
+        }
+        if (arg === '--debug') {
+            options.debug = true;
+            continue;
+        }
+        if (arg === '--sock') {
+            i++;
+            if (i >= args.length) {
+                console.error('Error: --sock requires a socket path argument.');
+                process.exit(1);
+            }
+            options.socketPath = args[i];
+            continue;
+        }
+        if (arg.startsWith('--sock=')) {
+            options.socketPath = arg.slice('--sock='.length);
+            continue;
+        }
+        if (arg === '--face') {
+            i++;
+            if (i >= args.length) {
+                console.error('Error: --face requires a path argument.');
+                process.exit(1);
+            }
+            options.facePath = args[i];
+            continue;
+        }
+        if (arg.startsWith('--face=')) {
+            options.facePath = arg.slice('--face='.length);
+            continue;
+        }
+        if (arg === '--theme') {
+            i++;
+            if (i >= args.length) {
+                console.error('Error: --theme requires a value (dark, light, or auto).');
+                process.exit(1);
+            }
+            const value = args[i];
+            if (value !== 'dark' && value !== 'light' && value !== 'auto') {
+                console.error(`Error: invalid theme "${value}". Must be dark, light, or auto.`);
+                process.exit(1);
+            }
+            options.theme = value;
+            continue;
+        }
+        if (arg.startsWith('--theme=')) {
+            const value = arg.slice('--theme='.length);
+            if (value !== 'dark' && value !== 'light' && value !== 'auto') {
+                console.error(`Error: invalid theme "${value}". Must be dark, light, or auto.`);
+                process.exit(1);
+            }
+            options.theme = value;
+            continue;
+        }
+        console.error(`Error: unknown option "${arg}".`);
+        process.exit(1);
+    }
+    return options;
+}
+// ── Help text ───────────────────────────────────────────────────────
+const HELP_TEXT = `\
+cc-face — Animated ASCII face for Claude Code
+
+Usage: cc-face [options]
+
+Options:
+  --face <path>          Load a custom face definition
+  -display, -f           Run only the face renderer (connect to running wrapper)
+  --sock <path>          Socket path to connect to (used with -display)
+  --theme dark|light|auto  Color theme (default: auto)
+  --no-face              Run Claude without the face overlay
+  --debug                Print diagnostic info before launching
+  -h, --help             Show this help
+  -v, --version          Show version`;
+// ── Main ────────────────────────────────────────────────────────────
+const options = parseArgs(process.argv);
+if (options.help) {
+    console.log(HELP_TEXT);
+    process.exit(0);
+}
+if (options.version) {
+    const require = createRequire(import.meta.url);
+    const pkg = require('../package.json');
+    console.log(pkg.version);
+    process.exit(0);
+}
+async function main() {
+    if (options.debug) {
+        const { findClaude, resolveSymlink } = await import('../src/pty.js');
+        try {
+            const claudePath = findClaude();
+            const target = resolveSymlink(claudePath);
+            console.error(`[debug] claude path: ${claudePath}${target ? ` -> ${target} (symlink)` : ''}`);
+        }
+        catch (err) {
+            console.error(`[debug] claude path: NOT FOUND (${err instanceof Error ? err.message : err})`);
+        }
+        const cols = process.stdout.columns ?? '?';
+        const rows = process.stdout.rows ?? '?';
+        console.error(`[debug] terminal: ${cols}x${rows}`);
+        console.error(`[debug] node: ${process.version}, platform: ${process.platform} ${process.arch}`);
+        console.error(`[debug] cwd: ${process.cwd()}`);
+    }
+    await run(options);
+}
+main().catch((err) => {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`cc-face: ${message}`);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/bin/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../bin/cli.ts"],"names":[],"mappings":"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"}

package/dist/src/config.d.ts

@@ -0,0 +1,24 @@
+export declare const config: {
+    /** Minimum ms between normal animation frames (~6 fps). */
+    minRenderIntervalMs: number;
+    /** Total duration of the per-character flip transition (ms). */
+    transitionDurationMs: number;
+    /** Render interval during a transition (~30 fps). */
+    transitionTickMs: number;
+    /** Logistic steepness — higher = sharper sigmoid S-curve. */
+    sigmoidSteepness: number;
+    /** No PTY activity for this long → idle. */
+    idleTimeoutMs: number;
+    /** Debounce window before committing a state change. */
+    debounceMs: number;
+    /** How often accumulated PTY data is processed (ms). */
+    feedSampleIntervalMs: number;
+    /** Minimum printable chars in a PTY chunk to trigger 'typing'. */
+    minPrintableLen: number;
+    /** After a thinking pattern, suppress typing transitions for this long. */
+    thinkingCooldownMs: number;
+    /** Inactivity timeout before leaving 'listening' state. */
+    listeningTimeoutMs: number;
+    /** Delay before retrying a failed IPC connection (ms). */
+    ipcRetryMs: number;
+};

package/dist/src/config.js

@@ -0,0 +1,32 @@
+// ── Tunable constants ───────────────────────────────────────────────
+//
+// All timing, rendering, and state-detection knobs in one place.
+export const config = {
+    // ── Rendering ───────────────────────────────────────────────────
+    /** Minimum ms between normal animation frames (~6 fps). */
+    minRenderIntervalMs: 166,
+    // ── Transitions ─────────────────────────────────────────────────
+    /** Total duration of the per-character flip transition (ms). */
+    transitionDurationMs: 80,
+    /** Render interval during a transition (~30 fps). */
+    transitionTickMs: 33,
+    /** Logistic steepness — higher = sharper sigmoid S-curve. */
+    sigmoidSteepness: 7,
+    // ── State detection ─────────────────────────────────────────────
+    /** No PTY activity for this long → idle. */
+    idleTimeoutMs: 500,
+    /** Debounce window before committing a state change. */
+    debounceMs: 100,
+    /** How often accumulated PTY data is processed (ms). */
+    feedSampleIntervalMs: 50,
+    /** Minimum printable chars in a PTY chunk to trigger 'typing'. */
+    minPrintableLen: 3,
+    /** After a thinking pattern, suppress typing transitions for this long. */
+    thinkingCooldownMs: 400,
+    /** Inactivity timeout before leaving 'listening' state. */
+    listeningTimeoutMs: 1000,
+    // ── IPC ─────────────────────────────────────────────────────────
+    /** Delay before retrying a failed IPC connection (ms). */
+    ipcRetryMs: 1000,
+};
+//# sourceMappingURL=config.js.map

package/dist/src/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,EAAE;AACF,iEAAiE;AAEjE,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,mEAAmE;IACnE,2DAA2D;IAC3D,mBAAmB,EAAE,GAAG;IAExB,mEAAmE;IACnE,gEAAgE;IAChE,oBAAoB,EAAE,EAAE;IACxB,qDAAqD;IACrD,gBAAgB,EAAE,EAAE;IACpB,6DAA6D;IAC7D,gBAAgB,EAAE,CAAC;IAEnB,mEAAmE;IACnE,4CAA4C;IAC5C,aAAa,EAAE,GAAG;IAClB,wDAAwD;IACxD,UAAU,EAAE,GAAG;IACf,wDAAwD;IACxD,oBAAoB,EAAE,EAAE;IACxB,kEAAkE;IAClE,eAAe,EAAE,CAAC;IAClB,2EAA2E;IAC3E,kBAAkB,EAAE,GAAG;IACvB,2DAA2D;IAC3D,kBAAkB,EAAE,IAAI;IAExB,mEAAmE;IACnE,0DAA0D;IAC1D,UAAU,EAAE,IAAI;CACjB,CAAC"}

package/dist/src/face.d.ts

@@ -0,0 +1,59 @@
+import { FaceDefinition, FaceState, ColorSpan, ThemeColors } from './types.js';
+/**
+ * Render a single art row with ANSI color spans applied.
+ * Accepts pre-sorted spans for this specific row only.
+ */
+export declare function renderRow(art: string, rowSpans: ColorSpan[], theme: ThemeColors): string;
+export declare class FaceRenderer {
+    private face;
+    private theme;
+    private currentState;
+    private currentFrameIndex;
+    private animationTimer;
+    private cycleStartTime;
+    private animCycleDuration;
+    private animForwardDuration;
+    private animFrameDuration;
+    private animFrameCount;
+    private animHasReverse;
+    private animGapMin;
+    private animGapMax;
+    private animTickMs;
+    private stdoutDraining;
+    private hasRenderedOnce;
+    private lastRenderedState;
+    private lastRenderedFrame;
+    private frameCache;
+    private clearScreenBuf;
+    private cachedCols;
+    private cachedRows;
+    private transitioning;
+    private transitionTimer;
+    private transitionStartTime;
+    private transitionFlipTimes;
+    private transitionOldArt;
+    private transitionNewArt;
+    private transitionOldRoles;
+    private transitionNewRoles;
+    private transitionNewState;
+    constructor(face: FaceDefinition, theme: ThemeColors);
+    private rebuildFrameCache;
+    setState(state: FaceState): void;
+    invalidateCache(): void;
+    showMessage(msg: string): void;
+    destroy(): void;
+    private buildRoleGrid;
+    private generateFlipTimes;
+    private beginTransition;
+    private scheduleTransitionTick;
+    private transitionTick;
+    private finishTransition;
+    private stopTransition;
+    private renderTransitionFrame;
+    private startAnimation;
+    private startNewCycle;
+    private scheduleNextTick;
+    private animationTick;
+    private stopAnimation;
+    private renderNow;
+}