@cobanalitalha/claude-spinner 2.0.0

package/README.md

@@ -0,0 +1,77 @@
+# claude-spinner
+
+Animated spinners for your Claude Code session.
+
+`claude-spinner` hooks into [Claude Code](https://claude.ai/code) and runs a small animation in the top-right corner of your terminal while Claude is working. A random animation is chosen each session.
+
+---
+
+## Animations
+
+| Name | Description | Speed |
+|------|-------------|-------|
+| `coffee` | Steam drifting above a coffee cup | 350 ms |
+| `rocket` | Exhaust flame pulsing beneath a rocket | 180 ms |
+| `clock` | Arrow hand spinning around a dial | 130 ms |
+| `ball` | Ball bouncing inside a box | 110 ms |
+
+---
+
+## How it works
+
+- A background daemon draws the animation directly to your terminal using `/dev/tty`, so it never interferes with Claude's output.
+- The spinner appears the moment Claude starts using a tool and disappears cleanly when Claude finishes responding.
+- If the hook's stdin is piped (non-TTY), the daemon resolves the real terminal device by walking up the process tree.
+
+---
+
+## Installation
+
+```bash
+npm install -g claude-spinner
+claude-spinner install
+```
+
+Then restart Claude Code. That's it.
+
+`claude-spinner install` adds two hooks to `~/.claude/settings.json`:
+
+| Hook | Command | Effect |
+|------|---------|--------|
+| `PreToolUse` | `claude-spinner start` | Starts the daemon when Claude begins working |
+| `Stop` | `claude-spinner stop` | Stops the daemon when Claude finishes |
+
+---
+
+## Requirements
+
+- Node.js 18 or later
+- macOS or Linux (requires `/dev/tty` access)
+- [Claude Code](https://claude.ai/code) CLI
+
+---
+
+## Commands
+
+```bash
+claude-spinner install     # Add hooks to ~/.claude/settings.json
+claude-spinner uninstall   # Remove hooks from ~/.claude/settings.json
+claude-spinner start       # Start the spinner daemon manually
+claude-spinner stop        # Stop the spinner daemon
+claude-spinner status      # Show whether the daemon is running
+```
+
+---
+
+## Uninstall
+
+```bash
+claude-spinner uninstall
+npm uninstall -g claude-spinner
+```
+
+---
+
+## License
+
+MIT

package/bin/claude-spinner.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+'use strict';
+
+const [,, command] = process.argv;
+
+switch (command) {
+  case 'start': {
+    require('../src/daemon').start();
+    break;
+  }
+
+  case 'stop': {
+    require('../src/daemon').stop();
+    break;
+  }
+
+  case 'install': {
+    require('../src/install').install();
+    break;
+  }
+
+  case 'uninstall': {
+    require('../src/install').uninstall();
+    break;
+  }
+
+  case 'status': {
+    const fs      = require('fs');
+    const path    = require('path');
+    const os      = require('os');
+    const pidFile = path.join(os.tmpdir(), 'claude-spinner.pid');
+    try {
+      const pid = parseInt(fs.readFileSync(pidFile, 'utf8').trim(), 10);
+      process.kill(pid, 0);
+      console.log(`Running (pid ${pid})`);
+    } catch {
+      console.log('Not running');
+    }
+    break;
+  }
+
+  default: {
+    console.log(`
+  ┌──────────────────────────────────────────────────┐
+  │             claude-spinner  v2.0.0               │
+  │   Animated spinners for your Claude Code session │
+  └──────────────────────────────────────────────────┘
+
+  COMMANDS
+    install     Add hooks to ~/.claude/settings.json
+    uninstall   Remove hooks from ~/.claude/settings.json
+    start       Start the spinner animation daemon
+    stop        Stop the spinner animation daemon
+    status      Show whether the daemon is running
+
+  QUICK START
+    npm install -g claude-spinner
+    claude-spinner install
+    # Then open Claude Code – a spinner appears automatically!
+
+  HOW IT WORKS
+    • Draws an animated spinner in the top-right corner of
+      your terminal using /dev/tty (never interferes with output).
+    • A random animation is chosen each session:
+        coffee  – steam rising from a cup
+        rocket  – exhaust flame pulsing beneath a rocket
+        clock   – arrow hand spinning around a dial
+        ball    – ball bouncing inside a box
+    • Starts automatically when Claude uses a tool and stops
+      when Claude finishes responding.
+`);
+  }
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@cobanalitalha/claude-spinner",
+  "version": "2.0.0",
+  "description": "Animated spinners for your Claude Code session",
+  "bin": {
+    "claude-spinner": "bin/claude-spinner.js"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "terminal",
+    "animation",
+    "spinner",
+    "hooks"
+  ],
+  "author": "Ali Talha ÇOBAN",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/carpodok/claude-spinner.git"
+  }
+}

package/src/animations.js

@@ -0,0 +1,135 @@
+'use strict';
+
+// ANSI colour codes
+const Y   = '\x1b[33m';   // yellow
+const C   = '\x1b[36m';   // cyan
+const G   = '\x1b[32m';   // green
+const R   = '\x1b[31m';   // red
+const W   = '\x1b[37m';   // white
+const DIM = '\x1b[2m';
+const RS  = '\x1b[0m';    // reset
+
+// ─────────────────────────────────────────────────────────────────────────
+// 1. COFFEE CUP  –  steam drifts above the cup
+//    Width: 13   Height: 7   Interval: 350 ms
+// ─────────────────────────────────────────────────────────────────────────
+const STEAM = [
+  '  ~   ~   ~  ',   // frame 0  (all 13 visible chars)
+  '   ~   ~   ~ ',   // frame 1
+  '~   ~   ~    ',   // frame 2
+  ' ~   ~   ~   ',   // frame 3
+];
+
+const CUP_BODY = [
+  `${Y}  .-------.  ${RS}`,
+  `${Y} |         | ${RS}`,
+  `${Y} |         |)${RS}`,
+  `${Y}  '-------'  ${RS}`,
+  `             `,
+  `             `,
+];
+
+const coffee = {
+  name: 'coffee',
+  width: 13,
+  intervalMs: 350,
+  frames: STEAM.map(s => [`${DIM}${s}${RS}`, ...CUP_BODY]),
+};
+
+// ─────────────────────────────────────────────────────────────────────────
+// 2. ROCKET  –  exhaust flame pulses beneath the rocket
+//    Width: 10   Height: 7   Interval: 180 ms
+// ─────────────────────────────────────────────────────────────────────────
+const EXHAUST = [
+  `   *  *   `,   // frame 0  (10 visible chars)
+  `  **  **  `,   // frame 1
+  ` **** *** `,   // frame 2
+  `  **  **  `,   // frame 3
+];
+
+const ROCKET_BODY = [
+  `${W}    /\\    ${RS}`,
+  `${W}   /  \\   ${RS}`,
+  `${W}  | ${C}**${W} |  ${RS}`,
+  `${W}  |    |  ${RS}`,
+  `${W}  '----'  ${RS}`,
+];
+
+const rocket = {
+  name: 'rocket',
+  width: 10,
+  intervalMs: 180,
+  frames: EXHAUST.map(e => [
+    ...ROCKET_BODY,
+    `${R}${e}${RS}`,
+    `          `,
+  ]),
+};
+
+// ─────────────────────────────────────────────────────────────────────────
+// 3. CLOCK  –  arrow hand rotates around the dial
+//    Width: 11   Height: 7   Interval: 130 ms
+// ─────────────────────────────────────────────────────────────────────────
+const CLOCK_ARROWS = ['↑', '↗', '→', '↘', '↓', '↙', '←', '↖'];
+
+const clock = {
+  name: 'clock',
+  width: 11,
+  intervalMs: 130,
+  frames: CLOCK_ARROWS.map(arrow => [
+    `${C}   .---.   ${RS}`,
+    `${C}  /     \\  ${RS}`,
+    `${C}  |  ${Y}${arrow}${C}  |  ${RS}`,
+    `${C}  |     |  ${RS}`,
+    `${C}  \\     /  ${RS}`,
+    `${C}   '---'   ${RS}`,
+    `           `,
+  ]),
+};
+
+// ─────────────────────────────────────────────────────────────────────────
+// 4. BOUNCING BALL  –  ball ricochets inside a box
+//    Width: 14   Height: 7   Interval: 110 ms
+// ─────────────────────────────────────────────────────────────────────────
+function makeBallFrames() {
+  const X_MAX = 11;   // x: 0 .. 11  (12 interior columns)
+  const Y_MAX = 2;    // y: 0 .. 2   (3 interior rows)
+  let x = 0, y = 0, vx = 1, vy = 1;
+  const frames = [];
+
+  const top = `${DIM}.------------.${RS}`;
+  const bot = `${DIM}'------------'${RS}`;
+  const pad = `              `;  // 14 spaces
+
+  for (let f = 0; f < 28; f++) {
+    const rows = [];
+    for (let row = 0; row <= Y_MAX; row++) {
+      const interior = row === y
+        ? ' '.repeat(x) + `${G}●${RS}` + ' '.repeat(X_MAX - x)
+        : ' '.repeat(X_MAX + 1);
+      rows.push(`${DIM}|${RS}${interior}${DIM}|${RS}`);
+    }
+    frames.push([top, ...rows, bot, pad, pad]);
+
+    // Move and bounce
+    x += vx; y += vy;
+    if (x <= 0)      { x = 0;      vx =  1; }
+    if (x >= X_MAX)  { x = X_MAX;  vx = -1; }
+    if (y <= 0)      { y = 0;      vy =  1; }
+    if (y >= Y_MAX)  { y = Y_MAX;  vy = -1; }
+  }
+
+  return frames;
+}
+
+const ball = {
+  name: 'ball',
+  width: 14,
+  intervalMs: 110,
+  frames: makeBallFrames(),
+};
+
+// ─────────────────────────────────────────────────────────────────────────
+// Export – add new animations to this object; daemon picks one at random.
+// ─────────────────────────────────────────────────────────────────────────
+module.exports = { coffee, rocket, clock, ball };

package/src/daemon.js

@@ -0,0 +1,175 @@
+'use strict';
+
+/**
+ * daemon.js
+ *
+ * Two responsibilities:
+ *   1. Exported API: start() / stop() – called from the CLI to manage the daemon process.
+ *   2. Daemon main loop – runs when this file is the entry point with the --daemon flag.
+ *
+ * KEY DESIGN NOTE
+ * ───────────────
+ * The daemon is spawned with `detached: true`, which means it loses its controlling
+ * terminal and cannot open /dev/tty.  We work around this by resolving the real TTY
+ * device path (e.g. /dev/ttys003 on macOS, /dev/pts/2 on Linux) *before* detaching
+ * and passing it via the SPINNER_TTY environment variable.  A detached process can still
+ * open a specific device node by path as long as it has permission.
+ */
+
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+const { spawn, execSync } = require('child_process');
+
+const PID_FILE   = path.join(os.tmpdir(), 'claude-spinner.pid');
+const DAEMON_ARG = '--daemon';
+
+// ─────────────────────────────────────────────────────────────
+// Public API
+// ─────────────────────────────────────────────────────────────
+
+function isAlive(pid) {
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+
+function readPid() {
+  try { return parseInt(fs.readFileSync(PID_FILE, 'utf8').trim(), 10); } catch { return null; }
+}
+
+/** Find the real TTY device path for the current process. Returns null if not a TTY. */
+function resolveTTY() {
+  // 1. Direct check – works when hook stdin is still connected to the terminal
+  try {
+    const out = execSync('tty', { encoding: 'utf8', stdio: ['inherit', 'pipe', 'pipe'] }).trim();
+    if (out && out !== 'not a tty' && fs.existsSync(out)) return out;
+  } catch {}
+
+  // 2. Walk up the process tree looking for a parent that owns a TTY.
+  //    Claude Code itself always runs in a real terminal, so one of the
+  //    ancestor processes will have a TTY even if the hook's stdio is piped.
+  try {
+    let pid = process.ppid;
+    for (let depth = 0; depth < 5 && pid > 1; depth++) {
+      const ttyName = execSync(`ps -o tty= -p ${pid} 2>/dev/null`, { encoding: 'utf8' }).trim();
+      if (ttyName && ttyName !== '??' && ttyName !== '?') {
+        // macOS: "s003" → "/dev/ttys003"  |  Linux: "pts/2" → "/dev/pts/2"
+        const ttyPath = ttyName.startsWith('/')   ? ttyName
+                      : ttyName.startsWith('pts/') ? `/dev/${ttyName}`
+                      : `/dev/tty${ttyName}`;
+        if (fs.existsSync(ttyPath)) return ttyPath;
+      }
+      // Move up one level
+      const ppid = execSync(`ps -o ppid= -p ${pid} 2>/dev/null`, { encoding: 'utf8' }).trim();
+      pid = parseInt(ppid, 10);
+      if (!pid || isNaN(pid)) break;
+    }
+  } catch {}
+
+  return null; // not a supported environment – fail silently
+}
+
+function start() {
+  const pid = readPid();
+  if (pid && isAlive(pid)) return; // already running
+
+  const ttyPath = resolveTTY();
+  if (!ttyPath) return; // not a TTY environment – silently do nothing
+
+  const cols = (process.stdout.columns || 80).toString();
+
+  const child = spawn(process.execPath, [__filename, DAEMON_ARG], {
+    detached: true,
+    stdio: 'ignore',
+    env: { ...process.env, SPINNER_TTY: ttyPath, SPINNER_COLS: cols },
+  });
+  child.unref();
+
+  try { fs.writeFileSync(PID_FILE, String(child.pid)); } catch {}
+}
+
+function stop() {
+  const pid = readPid();
+  if (!pid) return;
+  try { process.kill(pid, 'SIGTERM'); } catch {}
+  try { fs.unlinkSync(PID_FILE); } catch {}
+}
+
+module.exports = { start, stop };
+
+// ─────────────────────────────────────────────────────────────
+// Daemon entry point
+// ─────────────────────────────────────────────────────────────
+
+if (require.main === module && process.argv.includes(DAEMON_ARG)) {
+  runDaemon().catch(() => process.exit(1));
+}
+
+// ─────────────────────────────────────────────────────────────
+// Daemon implementation
+// ─────────────────────────────────────────────────────────────
+
+async function runDaemon() {
+  const animations = require('./animations');
+  const keys = Object.keys(animations);
+  const anim = animations[keys[Math.floor(Math.random() * keys.length)]];
+
+  const ttyPath = process.env.SPINNER_TTY;
+  if (!ttyPath) process.exit(1);
+
+  let ttyFd;
+  try {
+    ttyFd = fs.openSync(ttyPath, 'r+');
+  } catch {
+    process.exit(1);
+  }
+
+  const cols   = parseInt(process.env.SPINNER_COLS || '80', 10);
+  const col    = Math.max(1, cols - anim.width + 1);
+  const HEIGHT = anim.frames[0].length;
+
+  function writeTTY(str) {
+    try { fs.writeSync(ttyFd, str); } catch {}
+  }
+
+  /** Draw a frame at the fixed top-right position without disturbing Claude's cursor. */
+  function draw(frame) {
+    let buf = '\x1b7'; // DECSC: save cursor
+    for (let i = 0; i < frame.length; i++) {
+      buf += `\x1b[${i + 1};${col}H${frame[i]}`;
+    }
+    buf += '\x1b8'; // DECRC: restore cursor
+    writeTTY(buf);
+  }
+
+  /** Erase the spinner area on exit. */
+  function clear() {
+    const blank = ' '.repeat(anim.width + 2);
+    let buf = '\x1b7';
+    for (let i = 0; i < HEIGHT; i++) {
+      buf += `\x1b[${i + 1};${col}H${blank}`;
+    }
+    buf += '\x1b8';
+    writeTTY(buf);
+  }
+
+  function sleep(ms) {
+    return new Promise(r => setTimeout(r, ms));
+  }
+
+  // Graceful shutdown: clear the spinner then exit.
+  process.on('SIGTERM', () => {
+    clear();
+    try { fs.unlinkSync(PID_FILE); } catch {}
+    process.exit(0);
+  });
+
+  // ── Animation loop ──────────────────────────────────────────
+  let frameIdx = 0;
+  draw(anim.frames[0]);
+
+  while (true) {
+    await sleep(anim.intervalMs);
+    frameIdx = (frameIdx + 1) % anim.frames.length;
+    draw(anim.frames[frameIdx]);
+  }
+}

package/src/install.js

@@ -0,0 +1,110 @@
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+
+const SETTINGS_PATH = path.join(os.homedir(), '.claude', 'settings.json');
+
+// Hook entries we manage – identified by their command string
+const HOOK_START = 'claude-spinner start';
+const HOOK_STOP  = 'claude-spinner stop';
+
+// Legacy hook commands from the old "whip-claude" name – removed on install
+const LEGACY_START = 'whip-claude start';
+const LEGACY_STOP  = 'whip-claude stop';
+
+function readSettings() {
+  try {
+    const raw = fs.readFileSync(SETTINGS_PATH, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+
+function writeSettings(settings) {
+  const dir = path.dirname(SETTINGS_PATH);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(SETTINGS_PATH, JSON.stringify(settings, null, 2) + '\n', 'utf8');
+}
+
+// Return true if a hook command is already present in the list
+function hasHook(hookList, command) {
+  if (!Array.isArray(hookList)) return false;
+  return hookList.some((entry) =>
+    Array.isArray(entry.hooks) &&
+    entry.hooks.some((h) => h.command === command)
+  );
+}
+
+// Append a hook entry for the given command if not already present
+function addHook(hookList, command) {
+  if (hasHook(hookList, command)) return hookList;
+  return [
+    ...hookList,
+    {
+      matcher: '.*',
+      hooks: [{ type: 'command', command }],
+    },
+  ];
+}
+
+// Remove all hook entries whose command matches
+function removeHook(hookList, command) {
+  if (!Array.isArray(hookList)) return [];
+  return hookList.filter(
+    (entry) =>
+      !Array.isArray(entry.hooks) ||
+      !entry.hooks.some((h) => h.command === command)
+  );
+}
+
+function install() {
+  const settings = readSettings();
+  if (!settings.hooks) settings.hooks = {};
+
+  const h = settings.hooks;
+
+  // Remove legacy whip-claude hooks if present
+  h.PreToolUse = removeHook(h.PreToolUse || [], LEGACY_START);
+  h.Stop       = removeHook(h.Stop       || [], LEGACY_STOP);
+
+  h.PreToolUse = addHook(h.PreToolUse, HOOK_START);
+  h.Stop       = addHook(h.Stop,       HOOK_STOP);
+
+  writeSettings(settings);
+
+  console.log('✓ claude-spinner hooks installed in ~/.claude/settings.json');
+  console.log('  • PreToolUse → claude-spinner start');
+  console.log('  • Stop       → claude-spinner stop');
+  console.log('\nRestart Claude Code for the hooks to take effect.');
+}
+
+function uninstall() {
+  const settings = readSettings();
+  if (!settings.hooks) {
+    console.log('No hooks found – nothing to remove.');
+    return;
+  }
+
+  const h = settings.hooks;
+
+  h.PreToolUse = removeHook(h.PreToolUse, HOOK_START);
+  h.Stop       = removeHook(h.Stop,       HOOK_STOP);
+
+  // Also clean up legacy hooks if still present
+  h.PreToolUse = removeHook(h.PreToolUse, LEGACY_START);
+  h.Stop       = removeHook(h.Stop,       LEGACY_STOP);
+
+  // Clean up empty arrays
+  if (h.PreToolUse && h.PreToolUse.length === 0) delete h.PreToolUse;
+  if (h.Stop       && h.Stop.length       === 0) delete h.Stop;
+  if (Object.keys(h).length === 0) delete settings.hooks;
+
+  writeSettings(settings);
+
+  console.log('✓ claude-spinner hooks removed from ~/.claude/settings.json');
+}
+
+module.exports = { install, uninstall };