codex-copilot-dx 0.7.0 → 0.7.1

package/README.md

@@ -87,6 +87,28 @@ The selector first queries the running adapter, including its last-known-good mo
 
 The selection is saved in `~/.config/codex-copilot-dx/config.json`, or under `XDG_CONFIG_HOME` when set. Choosing `gpt-5.5` clears the override and restores the package default. A running adapter reads the setting on the next Auto-review request.
 
+### Terminal animation
+
+Choose the terminal activity animation interactively:
+
+```bash
+ccdx animation
+```
+
+The selector is ordered numerically:
+
+1. Comet (default)
+2. Twin
+3. Shuttle
+4. Chase
+5. Mirror
+6. Pulse
+7. Braille
+
+Enter the corresponding number to select an animation. The Comet row includes a static preview, and after a selection CCDX plays one cycle of the chosen animation as confirmation when terminal animation is enabled. The setting is saved in `~/.config/codex-copilot-dx/config.json`, or under `XDG_CONFIG_HOME` when set.
+
+The selected theme is loaded once when a new adapter starts, so changing it does not restart or alter an adapter that is already running. Stop and start CCDX to apply the new theme. `CCDX_TERMINAL_ANIMATION=0` (also `false`, `no`, or `off`) remains the boolean gate that disables terminal animation regardless of the selected theme.
+
 ### Update
 
 Choose a source interactively:
@@ -197,7 +219,7 @@ ccdx
 | `CCDX_LOG_PATH` | unset | Mirror terminal logs to a file; set to `1` for `~/.local/share/codex-copilot-dx/debug.log` |
 | `CCDX_LOG_LEVEL` | `info` | Set to `debug` for upstream attempts, status codes, retry causes, and timings |
 | `CCDX_LOG_MAX_BYTES` | `16777216` | Rotate the debug log at this size and retain one `.1` backup; set to `0` to disable rotation |
-| `CCDX_TERMINAL_ANIMATION` | auto | Show a transient comet while an interactive terminal has active requests and no output for 800 ms; set to `0` to disable |
+| `CCDX_TERMINAL_ANIMATION` | auto | Show the selected transient animation while an interactive terminal has active requests and no output for 800 ms; set to `0`, `false`, `no`, or `off` to disable |
 | `CCDX_IMG_MAX_DIM` | `2048` | Maximum long edge in pixels for image downscaling |
 | `CCDX_IMG_QUALITY` | `82` | Initial WebP quality for image re-encoding |
 | `CCDX_IMG_MIN_BYTES` | `100000` | In-bounds images smaller than this remain unchanged; oversized images are still downscaled |

package/bin/cli.mjs

@@ -16,7 +16,7 @@ import { cliCommandName, cliHelp, parseAdapterProbeOptions, parseCliArgs, parseR
 import { formatAdapterStatus, readAdapterStatus } from "../src/cli-status.mjs";
 import { closeHttpServer } from "../src/shutdown.mjs";
 import { runAutoReviewModelCommand } from "../src/auto-review-model.mjs";
-import { autoReviewModelPreference } from "../src/user-settings.mjs";
+import { autoReviewModelPreference, terminalAnimationPreference } from "../src/user-settings.mjs";
 import { fetchLiveCopilotModels, formatLiveCopilotModels } from "../src/cli-models.mjs";
 import { runAuthCommand } from "../src/cli-auth.mjs";
 import { createProfileRuntime } from "../src/profile-runtime.mjs";
@@ -43,6 +43,16 @@ if (CLI.command === "version") {
   console.log(CLI_BANNER);
   process.exit(0);
 }
+if (CLI.command === "animation") {
+  try {
+    const { runAnimationCommand } = await import("../src/cli-animation.mjs");
+    await runAnimationCommand({ commandName: CLI_NAME });
+    process.exit(0);
+  } catch (e) {
+    console.error(status("err", e.message));
+    process.exit(1);
+  }
+}
 if (CLI.command === "usage") {
   await printUsageSummary({
     format: CLI.outputFormat || "auto",
@@ -231,6 +241,7 @@ try {
   }
 
   // Start the in-process adapter.
+  const terminalAnimationTheme = terminalAnimationPreference().theme;
   activeServer = await startAdapter(ADAPTER_PORT, ADAPTER_HOST, {
     autoReviewModelResolver: () => autoReviewModelPreference().model,
     codexClient: profileRuntime.codexClient,
@@ -239,6 +250,7 @@ try {
     upstreamTimeoutMs: RUNTIME.upstreamTimeoutMs,
     streamHandshakeTimeoutMs: RUNTIME.streamHandshakeTimeoutMs,
     streamIdleTimeoutMs: RUNTIME.streamIdleTimeoutMs,
+    terminalAnimationTheme,
   });
 
   // Point Codex and compatible ChatGPT App builds at the adapter.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-copilot-dx",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Use Codex Desktop and ChatGPT App with GitHub Copilot",
   "author": "Dale Xiao",
   "type": "module",

package/src/adapter.mjs

@@ -311,7 +311,9 @@ export function createAdapterHandler(options = {}) {
 
 export function startAdapter(port = 2026, host = "127.0.0.1", options = {}) {
   const ownsTerminalActivity = !Object.hasOwn(options, "terminalActivity");
-  const terminalActivity = ownsTerminalActivity ? createTerminalActivityIndicator() : options.terminalActivity;
+  const terminalActivity = ownsTerminalActivity
+    ? createTerminalActivityIndicator({ theme: options.terminalAnimationTheme })
+    : options.terminalActivity;
   const handler = createAdapterHandler({ ...options, terminalActivity });
   const server = http.createServer(handler);
   const cleanupTerminalActivity = () => {

package/src/cli-animation.mjs

@@ -0,0 +1,108 @@
+import os from "node:os";
+import { createInterface } from "node:readline/promises";
+import {
+  DEFAULT_TERMINAL_ANIMATION_THEME,
+  playTerminalAnimationPreview,
+  renderTerminalAnimationFrame,
+  TERMINAL_ANIMATION_THEMES,
+} from "./terminal-animation.mjs";
+import {
+  readUserSettings,
+  terminalAnimationPreference,
+  writeTerminalAnimationTheme,
+} from "./user-settings.mjs";
+
+const DISABLED_ENV_VALUES = new Set(["0", "false", "no", "off"]);
+
+function markers(theme, currentTheme) {
+  const values = [];
+  if (theme.id === DEFAULT_TERMINAL_ANIMATION_THEME) values.push("default");
+  if (theme.id === currentTheme) values.push("current");
+  return values.length ? ` [${values.join(", ")}]` : "";
+}
+
+function disabledEnvironmentValue(env) {
+  const value = String(env.CCDX_TERMINAL_ANIMATION || "").trim();
+  return DISABLED_ENV_VALUES.has(value.toLowerCase()) ? value : "";
+}
+
+export async function runAnimationCommand({
+  commandName = "ccdx",
+  env = process.env,
+  home = os.homedir(),
+  input = process.stdin,
+  output = process.stdout,
+  prompt,
+  preview = playTerminalAnimationPreview,
+} = {}) {
+  if (!prompt && (!input.isTTY || !output.isTTY)) {
+    throw new Error(`${commandName} animation requires an interactive terminal`);
+  }
+
+  readUserSettings({ env, home, strict: true });
+  const current = terminalAnimationPreference({ env, home });
+  const currentIndex = TERMINAL_ANIMATION_THEMES.findIndex(({ id }) => id === current.theme);
+
+  output.write(`${commandName} animation\n`);
+  output.write(`Current: ${TERMINAL_ANIMATION_THEMES[currentIndex].label} (${current.source})\n\n`);
+  TERMINAL_ANIMATION_THEMES.forEach((theme, index) => {
+    const staticPreview = theme.id === DEFAULT_TERMINAL_ANIMATION_THEME
+      ? `  ${renderTerminalAnimationFrame(theme.id, 10)}`
+      : "";
+    output.write(`  ${index + 1}. ${theme.label}${markers(theme, current.theme)}${staticPreview}\n`);
+  });
+
+  let readline;
+  const ask = prompt || (async (question) => {
+    readline ||= createInterface({ input, output });
+    return readline.question(question);
+  });
+
+  let selectedTheme = current.theme;
+  let keepCurrent = false;
+  try {
+    while (true) {
+      const answer = String(await ask(`Select [${currentIndex + 1}], or q to cancel: `) || "").trim();
+      if (answer.toLowerCase() === "q") {
+        output.write("No changes made.\n");
+        return { changed: false, cancelled: true, theme: current.theme };
+      }
+      if (answer === "") {
+        keepCurrent = true;
+        break;
+      }
+      const selectedIndex = Number(answer) - 1;
+      if (Number.isInteger(selectedIndex)
+          && selectedIndex >= 0
+          && selectedIndex < TERMINAL_ANIMATION_THEMES.length) {
+        selectedTheme = TERMINAL_ANIMATION_THEMES[selectedIndex].id;
+        break;
+      }
+      output.write(`Enter a number from 1 to ${TERMINAL_ANIMATION_THEMES.length}, or q to cancel.\n`);
+    }
+  } finally {
+    readline?.close();
+  }
+
+  const result = keepCurrent
+    ? { changed: false, theme: current.theme }
+    : writeTerminalAnimationTheme(selectedTheme, { env, home });
+  const disabledValue = disabledEnvironmentValue(env);
+  if (!disabledValue) {
+    try {
+      await preview(selectedTheme, { output });
+    } catch {
+      output.write("[WARN] Preview unavailable; the terminal animation setting was still applied.\n");
+    }
+  }
+
+  const selected = TERMINAL_ANIMATION_THEMES.find(({ id }) => id === selectedTheme);
+  output.write(`${result.changed ? "Saved" : "Kept"} terminal animation: ${selected.label}\n`);
+  if (disabledValue) {
+    output.write(`CCDX_TERMINAL_ANIMATION=${disabledValue} remains effective until it is unset; terminal animation stays disabled.\n`);
+    output.write("The saved animation will be used on the next ccdx start after the override is unset.\n");
+  } else {
+    output.write("The next ccdx start will use this animation.\n");
+  }
+  return { ...result, cancelled: false, theme: selectedTheme };
+}

package/src/cli-options.mjs

@@ -19,6 +19,7 @@ const HELP_TOPICS = new Set([
   "status",
   "models",
   "usage",
+  "animation",
   "auto-review-model",
   "update",
   "version",
@@ -189,6 +190,10 @@ export function parseCliArgs(args = []) {
     }
     throw new Error(`Unknown auth action: ${action}`);
   }
+  if (command === "animation") {
+    if (rest.length) unexpectedArgs(rest);
+    return baseCommand("animation");
+  }
   if (command === "auto-review-model") {
     if (rest.length) unexpectedArgs(rest);
     return baseCommand("auto-review-model");
@@ -275,6 +280,7 @@ function topicHelp(name, topic) {
     status: `Usage:\n  ${name} status\n\nShows bounded runtime, routing, performance, queue, and cache metrics from a running adapter.`,
     models: `Usage:\n  ${name} models [--format table|plain]\n\nPerforms a fresh, read-only Copilot model-directory lookup for the saved account. Interactive terminals use a table by default.`,
     usage: `Usage:\n  ${name} usage [--format table|plain]\n\nSummarizes local token usage metadata without reading prompt or completion content. Interactive terminals use a table by default.`,
+    animation: `Usage:\n  ${name} animation\n\nInteractively selects the terminal activity animation used the next time the adapter starts.`,
     "auto-review-model": `Usage:\n  ${name} auto-review-model\n\nInteractively selects an enabled Responses model for Codex Auto-review.`,
     update: `Usage:\n  ${name} update [npm|github]\n\nUpdates the global package from the configured npm registry or GitHub main. With no source, an interactive terminal prompts for one.`,
     version: `Usage:\n  ${name} --version`,
@@ -293,6 +299,7 @@ export function cliHelp(commandName = "ccdx", topic = "") {
   ${name} status
   ${name} models [--format table|plain]
   ${name} usage [--format table|plain]
+  ${name} animation
   ${name} auto-review-model
   ${name} update [npm|github]
   ${name} --version
@@ -305,6 +312,7 @@ Commands:
   status             Show runtime routing, performance, queue, and cache health
   models             Query a saved account's live Copilot model catalog
   usage              Summarize locally recorded token usage
+  animation          Select the terminal activity animation
   auto-review-model  Select the Codex Auto-review Responses model
   update             Update the global package from npm or GitHub
 

package/src/terminal-activity.mjs

@@ -1,14 +1,21 @@
+import {
+  DEFAULT_TERMINAL_ANIMATION_THEME,
+  TERMINAL_ANIMATION_THEMES,
+  TERMINAL_ANIMATION_TRACK_WIDTH,
+  getTerminalAnimationCycleLength,
+  getTerminalAnimationFrameDelay,
+  isTerminalAnimationTheme,
+  renderTerminalAnimationFrame,
+} from "./terminal-animation.mjs";
+
+export { renderCometFrame } from "./terminal-animation.mjs";
+
 const ESC = "\u001b";
 const ERASE_LINE = `\r${ESC}[2K`;
 const HIDE_CURSOR = `${ESC}[?25l`;
 const SHOW_CURSOR = `${ESC}[?25h`;
 
-const TRACK_WIDTH = 20;
-const TAIL_LENGTH = 7;
 const IDLE_DELAY_MS = 800;
-const FRAME_DELAY_MS = 45;
-const LOOP_PAUSE_MS = 200;
-const TAIL_COLORS = [159, 123, 87, 51, 45, 39, 33];
 
 function envFlagEnabled(value) {
   const normalized = String(value || "").trim().toLowerCase();
@@ -21,22 +28,7 @@ function terminalActivityEnabled({ env, output, errorOutput }) {
   if (envFlagEnabled(env.CI) || String(env.TERM || "").toLowerCase() === "dumb") return false;
   if (output?.isTTY !== true || errorOutput?.isTTY !== true) return false;
   const columns = Number(output.columns);
-  return !Number.isFinite(columns) || columns <= 0 || columns >= TRACK_WIDTH + 2;
-}
-
-export function renderCometFrame(position) {
-  let track = "";
-  for (let column = 0; column < TRACK_WIDTH; column += 1) {
-    const distance = position - column;
-    if (distance === 0) {
-      track += `${ESC}[97m:${ESC}[0m`;
-    } else if (distance > 0 && distance <= TAIL_LENGTH) {
-      track += `${ESC}[38;5;${TAIL_COLORS[distance - 1]}m:${ESC}[0m`;
-    } else {
-      track += " ";
-    }
-  }
-  return `[${track}]`;
+  return !Number.isFinite(columns) || columns <= 0 || columns >= TERMINAL_ANIMATION_TRACK_WIDTH + 2;
 }
 
 function disabledIndicator() {
@@ -53,8 +45,13 @@ export function createTerminalActivityIndicator({
   errorOutput = process.stderr,
   consoleObj = console,
   timers = { setTimeout, clearTimeout },
+  theme = DEFAULT_TERMINAL_ANIMATION_THEME,
 } = {}) {
   if (!terminalActivityEnabled({ env, output, errorOutput })) return disabledIndicator();
+  if (!isTerminalAnimationTheme(theme)) throw new TypeError(`Unknown terminal animation theme: ${String(theme)}`);
+
+  const themeMetadata = TERMINAL_ANIMATION_THEMES.find(({ id }) => id === theme);
+  const cycleLength = getTerminalAnimationCycleLength(theme);
 
   const methods = ["log", "warn", "error", "debug"];
   const originals = Object.fromEntries(methods.map((method) => [method, consoleObj[method]]));
@@ -81,9 +78,12 @@ export function createTerminalActivityIndicator({
     clearTimer(frameTimer);
     frameTimer = null;
     framePosition = 0;
-    if (cursorHidden || frameVisible) output.write(`${ERASE_LINE}${SHOW_CURSOR}`);
-    cursorHidden = false;
-    frameVisible = false;
+    try {
+      if (cursorHidden || frameVisible) output.write(`${ERASE_LINE}${SHOW_CURSOR}`);
+    } finally {
+      cursorHidden = false;
+      frameVisible = false;
+    }
   };
 
   const cancelPendingOutput = () => {
@@ -98,20 +98,23 @@ export function createTerminalActivityIndicator({
       clearAnimation();
       return;
     }
-    if (framePosition >= TRACK_WIDTH + TAIL_LENGTH) {
-      output.write(ERASE_LINE);
-      frameVisible = false;
+    if (framePosition >= cycleLength) {
       framePosition = 0;
-      frameTimer = schedule(drawNextFrame, LOOP_PAUSE_MS);
-      return;
+      if (themeMetadata.loopPauseMs > 0) {
+        output.write(ERASE_LINE);
+        frameVisible = false;
+        frameTimer = schedule(drawNextFrame, themeMetadata.loopPauseMs);
+        return;
+      }
     }
 
+    const frameIndex = themeMetadata.startFrame + framePosition;
     const prefix = cursorHidden ? "" : HIDE_CURSOR;
     cursorHidden = true;
     frameVisible = true;
-    output.write(`${prefix}${ERASE_LINE}${renderCometFrame(framePosition)}`);
+    output.write(`${prefix}${ERASE_LINE}${renderTerminalAnimationFrame(theme, frameIndex)}`);
     framePosition += 1;
-    frameTimer = schedule(drawNextFrame, FRAME_DELAY_MS);
+    frameTimer = schedule(drawNextFrame, getTerminalAnimationFrameDelay(theme, frameIndex));
   };
 
   const scheduleAfterIdle = () => {
@@ -161,9 +164,12 @@ export function createTerminalActivityIndicator({
       activeRequests = 0;
       clearTimer(idleTimer);
       idleTimer = null;
-      clearAnimation();
-      for (const method of methods) {
-        if (consoleObj[method] === wrappers[method]) consoleObj[method] = originals[method];
+      try {
+        clearAnimation();
+      } finally {
+        for (const method of methods) {
+          if (consoleObj[method] === wrappers[method]) consoleObj[method] = originals[method];
+        }
       }
     },
   };

package/src/terminal-animation.mjs

@@ -0,0 +1,249 @@
+const ESC = "\u001b";
+
+export const TERMINAL_ANIMATION_TRACK_WIDTH = 20;
+export const DEFAULT_TERMINAL_ANIMATION_THEME = "comet";
+
+const TAIL_LENGTH = 7;
+const TAIL_COLORS = Object.freeze([159, 123, 87, 51, 45, 39, 33]);
+const BRAILLE_GLYPHS = Object.freeze(["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]);
+
+function colorCell(glyph, color) {
+  return `${ESC}[${color}m${glyph}${ESC}[0m`;
+}
+
+function blankTrack() {
+  return Array.from({ length: TERMINAL_ANIMATION_TRACK_WIDTH }, () => " ");
+}
+
+function setCell(cells, index, glyph, color) {
+  if (index < 0 || index >= TERMINAL_ANIMATION_TRACK_WIDTH) return;
+  cells[index] = colorCell(glyph, color);
+}
+
+function drawComet(cells, head, direction, tailLength = TAIL_LENGTH) {
+  for (let distance = tailLength; distance >= 1; distance -= 1) {
+    setCell(cells, head - (direction * distance), ":", `38;5;${TAIL_COLORS[distance - 1]}`);
+  }
+  setCell(cells, head, ":", "97");
+}
+
+function wrapTrack(cells) {
+  return `[${cells.join("")}]`;
+}
+
+function pingPongState(index) {
+  const period = (TERMINAL_ANIMATION_TRACK_WIDTH - 1) * 2;
+  const offset = index % period;
+  return offset < TERMINAL_ANIMATION_TRACK_WIDTH
+    ? { position: offset, direction: 1 }
+    : { position: period - offset, direction: -1 };
+}
+
+const THEME_DEFINITIONS = Object.freeze([
+  Object.freeze({
+    id: "comet",
+    label: "Comet",
+    frameCount: TERMINAL_ANIMATION_TRACK_WIDTH + TAIL_LENGTH,
+    frameDelayMs: 45,
+    loopPauseMs: 200,
+    startFrame: 0,
+    render: renderCometFrame,
+  }),
+  Object.freeze({
+    id: "twin",
+    label: "Twin",
+    frameCount: 26,
+    frameDelayMs: 60,
+    loopPauseMs: 0,
+    startFrame: 5,
+    render(index) {
+      const cells = blankTrack();
+      drawComet(cells, index - 3, 1, 4);
+      drawComet(cells, TERMINAL_ANIMATION_TRACK_WIDTH + 2 - index, -1, 4);
+      return wrapTrack(cells);
+    },
+  }),
+  Object.freeze({
+    id: "shuttle",
+    label: "Shuttle",
+    frameCount: (TERMINAL_ANIMATION_TRACK_WIDTH - 1) * 2,
+    frameDelayMs: 55,
+    loopPauseMs: 0,
+    startFrame: 7,
+    frameDelay(index) {
+      const { position } = pingPongState(index);
+      return position === 0 || position === TERMINAL_ANIMATION_TRACK_WIDTH - 1 ? 160 : 55;
+    },
+    render(index) {
+      const cells = blankTrack();
+      const { position, direction } = pingPongState(index);
+      drawComet(cells, position, direction);
+      return wrapTrack(cells);
+    },
+  }),
+  Object.freeze({
+    id: "chase",
+    label: "Chase",
+    frameCount: TERMINAL_ANIMATION_TRACK_WIDTH + 14,
+    frameDelayMs: 65,
+    loopPauseMs: 0,
+    startFrame: 13,
+    render(index) {
+      const cells = blankTrack();
+      const first = index - 4;
+      let second = first - 11;
+      if (second < -4) second += TERMINAL_ANIMATION_TRACK_WIDTH + 14;
+      drawComet(cells, first, 1, 4);
+      drawComet(cells, second, 1, 4);
+      return wrapTrack(cells);
+    },
+  }),
+  Object.freeze({
+    id: "mirror",
+    label: "Mirror",
+    frameCount: (Math.floor(TERMINAL_ANIMATION_TRACK_WIDTH / 2) - 1) * 2,
+    frameDelayMs: 75,
+    loopPauseMs: 0,
+    startFrame: 3,
+    render(index) {
+      const cells = blankTrack();
+      const half = Math.floor(TERMINAL_ANIMATION_TRACK_WIDTH / 2);
+      const period = (half - 1) * 2;
+      const distance = index < half ? index : period - index;
+      drawComet(cells, half - 1 - distance, -1, 3);
+      drawComet(cells, half + distance, 1, 3);
+      return wrapTrack(cells);
+    },
+  }),
+  Object.freeze({
+    id: "pulse",
+    label: "Pulse",
+    frameCount: 8,
+    frameDelayMs: 115,
+    loopPauseMs: 0,
+    startFrame: 2,
+    render(index) {
+      const cells = blankTrack();
+      const radii = [0, 1, 2, 3, 4, 3, 2, 1];
+      const radius = radii[index];
+      const center = Math.floor((TERMINAL_ANIMATION_TRACK_WIDTH - 1) / 2);
+      setCell(cells, center, ":", "97");
+      for (let distance = 1; distance <= radius; distance += 1) {
+        const color = `38;5;${TAIL_COLORS[distance]}`;
+        setCell(cells, center - distance, ":", color);
+        setCell(cells, center + distance, ":", color);
+      }
+      return wrapTrack(cells);
+    },
+  }),
+  Object.freeze({
+    id: "braille",
+    label: "Braille",
+    frameCount: BRAILLE_GLYPHS.length,
+    frameDelayMs: 80,
+    loopPauseMs: 0,
+    startFrame: 0,
+    render(index) {
+      const cells = blankTrack();
+      setCell(cells, Math.floor(TERMINAL_ANIMATION_TRACK_WIDTH / 2), BRAILLE_GLYPHS[index], `38;5;${TAIL_COLORS[2]}`);
+      return wrapTrack(cells);
+    },
+  }),
+]);
+
+const DEFINITIONS_BY_ID = new Map(THEME_DEFINITIONS.map((theme) => [theme.id, theme]));
+
+export const TERMINAL_ANIMATION_THEMES = Object.freeze(THEME_DEFINITIONS.map(({
+  id,
+  label,
+  frameCount,
+  frameDelayMs,
+  loopPauseMs,
+  startFrame,
+}) => Object.freeze({ id, label, frameCount, frameDelayMs, loopPauseMs, startFrame })));
+
+export function isTerminalAnimationTheme(value) {
+  return typeof value === "string" && DEFINITIONS_BY_ID.has(value);
+}
+
+function themeDefinition(theme) {
+  const definition = DEFINITIONS_BY_ID.get(theme);
+  if (!definition) throw new TypeError(`Unknown terminal animation theme: ${String(theme)}`);
+  return definition;
+}
+
+function normalizedFrameIndex(frameIndex, frameCount) {
+  if (!Number.isSafeInteger(frameIndex)) throw new TypeError("Terminal animation frame index must be an integer");
+  return ((frameIndex % frameCount) + frameCount) % frameCount;
+}
+
+export function getTerminalAnimationCycleLength(theme) {
+  return themeDefinition(theme).frameCount;
+}
+
+export function getTerminalAnimationFrameDelay(theme, frameIndex) {
+  const definition = themeDefinition(theme);
+  const index = normalizedFrameIndex(frameIndex, definition.frameCount);
+  return definition.frameDelay?.(index) ?? definition.frameDelayMs;
+}
+
+export function renderTerminalAnimationFrame(theme, frameIndex) {
+  const definition = themeDefinition(theme);
+  return definition.render(normalizedFrameIndex(frameIndex, definition.frameCount));
+}
+
+export function renderCometFrame(position) {
+  let track = "";
+  for (let column = 0; column < TERMINAL_ANIMATION_TRACK_WIDTH; column += 1) {
+    const distance = position - column;
+    if (distance === 0) {
+      track += `${ESC}[97m:${ESC}[0m`;
+    } else if (distance > 0 && distance <= TAIL_LENGTH) {
+      track += `${ESC}[38;5;${TAIL_COLORS[distance - 1]}m:${ESC}[0m`;
+    } else {
+      track += " ";
+    }
+  }
+  return `[${track}]`;
+}
+
+function outputSupportsPreview(output) {
+  if (output?.isTTY !== true) return false;
+  const columns = Number(output.columns);
+  return !Number.isFinite(columns) || columns <= 0 || columns >= TERMINAL_ANIMATION_TRACK_WIDTH + 2;
+}
+
+export async function playTerminalAnimationPreview(theme, {
+  output = process.stdout,
+  timers = { setTimeout, clearTimeout },
+} = {}) {
+  const definition = themeDefinition(theme);
+  if (!outputSupportsPreview(output)) return false;
+
+  const eraseLine = `\r${ESC}[2K`;
+  let timer = null;
+  let previewStarted = false;
+
+  const wait = (delay) => new Promise((resolve) => {
+    let settled = false;
+    const nextTimer = timers.setTimeout(() => {
+      settled = true;
+      timer = null;
+      resolve();
+    }, delay);
+    timer = settled ? null : nextTimer;
+  });
+
+  try {
+    for (let offset = 0; offset < definition.frameCount; offset += 1) {
+      const frameIndex = definition.startFrame + offset;
+      previewStarted = true;
+      output.write(`${eraseLine}${renderTerminalAnimationFrame(theme, frameIndex)}`);
+      await wait(getTerminalAnimationFrameDelay(theme, frameIndex));
+    }
+    return true;
+  } finally {
+    if (timer) timers.clearTimeout(timer);
+    if (previewStarted) output.write(eraseLine);
+  }
+}

package/src/user-settings.mjs

@@ -3,8 +3,14 @@ import os from "node:os";
 import path from "node:path";
 import { atomicWriteFileIfChangedSync } from "./atomic-file.mjs";
 import { DEFAULT_CODEX_AUTO_REVIEW_MODEL } from "./models.mjs";
+import {
+  DEFAULT_TERMINAL_ANIMATION_THEME,
+  isTerminalAnimationTheme,
+  TERMINAL_ANIMATION_THEMES,
+} from "./terminal-animation.mjs";
 
 const AUTO_REVIEW_MODEL_KEY = "auto_review_model";
+const TERMINAL_ANIMATION_KEY = "terminal_animation";
 
 export function userSettingsPath({ env = process.env, home = os.homedir() } = {}) {
   const xdgConfigHome = String(env.XDG_CONFIG_HOME || "").trim();
@@ -29,6 +35,16 @@ export function readUserSettings({ env = process.env, home = os.homedir(), stric
         throw invalidSettings(filePath, `${AUTO_REVIEW_MODEL_KEY} must be a non-empty string`);
       }
     }
+    if (Object.hasOwn(parsed, TERMINAL_ANIMATION_KEY)) {
+      const value = parsed[TERMINAL_ANIMATION_KEY];
+      if (!isTerminalAnimationTheme(value)) {
+        const choices = TERMINAL_ANIMATION_THEMES.map(({ id }) => id).join(", ");
+        if (strict) {
+          throw invalidSettings(filePath, `${TERMINAL_ANIMATION_KEY} must be one of: ${choices}`);
+        }
+        delete parsed[TERMINAL_ANIMATION_KEY];
+      }
+    }
     return parsed;
   } catch (error) {
     if (error?.code === "ENOENT") return {};
@@ -54,6 +70,18 @@ export function autoReviewModelPreference({ env = process.env, home = os.homedir
   return { model: DEFAULT_CODEX_AUTO_REVIEW_MODEL, source: "default" };
 }
 
+export function savedTerminalAnimationTheme(options = {}) {
+  const settings = readUserSettings(options);
+  const theme = settings[TERMINAL_ANIMATION_KEY];
+  return isTerminalAnimationTheme(theme) ? theme : "";
+}
+
+export function terminalAnimationPreference({ env = process.env, home = os.homedir() } = {}) {
+  const savedTheme = savedTerminalAnimationTheme({ env, home });
+  if (savedTheme) return { theme: savedTheme, source: "settings" };
+  return { theme: DEFAULT_TERMINAL_ANIMATION_THEME, source: "default" };
+}
+
 export function writeAutoReviewModel(model, { env = process.env, home = os.homedir() } = {}) {
   const filePath = userSettingsPath({ env, home });
   const settings = readUserSettings({ env, home, strict: true });
@@ -65,3 +93,25 @@ export function writeAutoReviewModel(model, { env = process.env, home = os.homed
   const changed = atomicWriteFileIfChangedSync(filePath, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
   return { changed, filePath, model: value || DEFAULT_CODEX_AUTO_REVIEW_MODEL };
 }
+
+export function writeTerminalAnimationTheme(theme, { env = process.env, home = os.homedir() } = {}) {
+  if (!isTerminalAnimationTheme(theme)) {
+    const choices = TERMINAL_ANIMATION_THEMES.map(({ id }) => id).join(", ");
+    throw new Error(`Terminal animation must be one of: ${choices}`);
+  }
+
+  const filePath = userSettingsPath({ env, home });
+  const settings = readUserSettings({ env, home, strict: true });
+  const next = { ...settings };
+  if (theme === DEFAULT_TERMINAL_ANIMATION_THEME) {
+    if (!Object.hasOwn(next, TERMINAL_ANIMATION_KEY)) {
+      return { changed: false, filePath, theme };
+    }
+    delete next[TERMINAL_ANIMATION_KEY];
+  } else {
+    next[TERMINAL_ANIMATION_KEY] = theme;
+  }
+
+  const changed = atomicWriteFileIfChangedSync(filePath, `${JSON.stringify(next, null, 2)}\n`, { mode: 0o600 });
+  return { changed, filePath, theme };
+}