codex-copilot-dx 0.7.0 → 0.7.2

package/README.md

@@ -1,8 +1,8 @@
 # codex-copilot-dx
 
-Use Codex Desktop or the ChatGPT app with GPT models provided by your **GitHub Copilot** subscription.
+Use Codex App with GPT models provided by your **GitHub Copilot** subscription.
 
-CCDX is a local compatibility adapter. It configures Codex-compatible desktop clients to use an OpenAI Responses API on loopback while GitHub authentication, model discovery, and inference stay backed by GitHub Copilot.
+CCDX is a local compatibility adapter for Codex App. It configures Codex to use an OpenAI Responses API on loopback while GitHub authentication, model discovery, and inference stay backed by GitHub Copilot.
 
 ## How it works
 
@@ -14,7 +14,7 @@ One in-process adapter listens on `127.0.0.1:2026` by default and exposes:
 
 Responses-only models and compaction use Copilot's Responses transport directly. For GPT models that advertise only Chat Completions, CCDX converts the supported text, image, and function-tool subset and rejects incompatible request shapes explicitly. Both streaming SSE and non-streaming responses are supported.
 
-The adapter preserves Codex and ChatGPT app behavior around response history, encrypted reasoning state, function/custom tools, images, compaction, cancellation, retries, and usage metadata. Model routing follows the live Copilot catalog instead of a hard-coded GPT model list.
+The adapter preserves Codex App behavior around response history, encrypted reasoning state, function/custom tools, images, compaction, cancellation, retries, and usage metadata. Model routing follows the live Copilot catalog instead of a hard-coded GPT model list.
 
 ### Fast and Standard modes
 
@@ -22,11 +22,17 @@ Codex can select Standard or Fast without changing CCDX configuration. When the
 
 Codex Auto-review uses the hidden `codex-auto-review` model ID. CCDX maps it to Copilot's `gpt-5.5` Responses model by default, independently of the interactive Fast/Standard selection, and logs both model IDs when the mapping is used. The review target can be changed interactively without reinstalling or restarting CCDX.
 
+### GPT-6 model catalog
+
+Codex App requests a versioned, capability-rich model catalog that is different from Copilot's raw model list. CCDX reads the complete catalog bundled with the installed Codex App and preserves every other model entry and capability. It makes `gpt-6-astra` visible only when the live Copilot catalog advertises that exact model as enabled, selectable, OpenAI-owned, and Responses-capable.
+
+CCDX 0.7.2 exposes only the verified GPT-6 Standard path and removes its unverified speed-tier metadata. Codex Ultra remains available because the client maps it to the model's supported multi-agent reasoning effort. GPT-5.6 Sol Fast remains unchanged. The bundled catalog is matched to the Codex client version, cached by application binary identity, and reloaded automatically after an App update.
+
 ## Prerequisites
 
 - GitHub Copilot subscription (Individual, Business, or Enterprise)
 - Node.js 22.15 or newer, for built-in Zstandard request decompression
-- Codex Desktop or the ChatGPT app on macOS
+- Codex App on macOS
 
 ## Install and start
 
@@ -49,7 +55,7 @@ On a normal launch, CCDX:
 2. Reuses a compatible running adapter when available; otherwise it reuses a compatible local Copilot credential or starts GitHub Device Flow when authentication is required.
 3. Refreshes Copilot model metadata and listens on the configured loopback address.
 4. Updates `~/.codex/config.toml` to use the local `/v1` endpoint while preserving unrelated Codex settings.
-5. Attempts to open Codex Desktop or the ChatGPT app on macOS unless `CCDX_AUTO_LAUNCH` disables it.
+5. Attempts to open Codex App on macOS unless `CCDX_AUTO_LAUNCH` disables it.
 
 The `OPENAI_API_KEY=dummy` value written into the Codex shell environment is only a client-side placeholder. It is not a GitHub credential. CCDX exchanges the saved GitHub OAuth credential for short-lived Copilot service tokens internally.
 
@@ -87,6 +93,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 +225,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 |
@@ -205,7 +233,7 @@ ccdx
 | `CCDX_IMG_MAX_INPUT_PIXELS` | `40000000` | Maximum decoded pixels accepted for one image |
 | `CCDX_IMG_CACHE_MAX_BYTES` | `67108864` | Process-local byte ceiling for cached image transforms; set to `0` to disable the cache |
 | `CCDX_DISABLE_IMG_OPT` | unset | Set to `1` to disable image optimization |
-| `CCDX_AUTO_LAUNCH` | enabled | Set to `0`, `false`, `no`, or `off` to start without opening Codex or ChatGPT |
+| `CCDX_AUTO_LAUNCH` | enabled | Set to `0`, `false`, `no`, or `off` to start without opening Codex App |
 | `CCDX_GITHUB_TOKEN` | unset | Explicit GitHub Copilot OAuth token to validate and import before Device Flow |
 | `CCDX_GITHUB_TOKEN_PATH` | unset | Explicit file containing a GitHub Copilot OAuth token |
 | `CCDX_GITHUB_TOKEN_PATHS` | unset | Multiple token files separated by the platform path delimiter (`:` on macOS/Linux, `;` on Windows) |
@@ -255,7 +283,7 @@ For `/v1/responses/compact`, CCDX sends one terminal `compaction_trigger`, valid
 
 Successful streaming responses are accepted only when the upstream body is SSE and reaches its protocol terminal event. Unexpected EOF becomes a protocol-native stream error, and repeated blank tool-argument deltas are stopped per tool call. Safe quota, retry, model, trace, and upstream request-ID metadata are forwarded; cookies, authorization, body-length, and encoding headers are not.
 
-Newer Codex and ChatGPT clients can advertise an `image_gen` namespace that already exists upstream. CCDX removes that exact conflicting client tool before forwarding and retries once only when Copilot explicitly reports an image namespace collision. Image input and screenshot optimization remain enabled.
+Newer Codex App builds can advertise an `image_gen` namespace that already exists upstream. CCDX removes that exact conflicting client tool before forwarding and retries once only when Copilot explicitly reports an image namespace collision. Image input and screenshot optimization remain enabled.
 
 ## Development
 

package/bin/cli.mjs

@@ -16,11 +16,12 @@ 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";
 import { createProfileModelRuntime } from "../src/profile-model-runtime.mjs";
+import { createCodexModelCatalog } from "../src/codex-model-catalog.mjs";
 
 const LOCAL_VERSION = localPackageVersion();
 const CLI_NAME = cliCommandName();
@@ -43,6 +44,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",
@@ -191,7 +202,7 @@ if (CLI.command === "doctor") {
 
 console.log(`
   ${CLI_BANNER}
-  Use Codex Desktop and ChatGPT App with GitHub Copilot
+  Use Codex App with GitHub Copilot
 `);
 
 async function printUpdateNotice() {
@@ -231,17 +242,21 @@ try {
   }
 
   // Start the in-process adapter.
+  const terminalAnimationTheme = terminalAnimationPreference().theme;
+  const codexModelCatalog = createCodexModelCatalog();
   activeServer = await startAdapter(ADAPTER_PORT, ADAPTER_HOST, {
     autoReviewModelResolver: () => autoReviewModelPreference().model,
     codexClient: profileRuntime.codexClient,
+    codexModelCatalog,
     codexModelRegistry: profileModels.codexRegistry,
     showRequestId: CLI.showRequestId,
     upstreamTimeoutMs: RUNTIME.upstreamTimeoutMs,
     streamHandshakeTimeoutMs: RUNTIME.streamHandshakeTimeoutMs,
     streamIdleTimeoutMs: RUNTIME.streamIdleTimeoutMs,
+    terminalAnimationTheme,
   });
 
-  // Point Codex and compatible ChatGPT App builds at the adapter.
+  // Point Codex App at the adapter.
   ensureCodexConfig(ADAPTER_PORT, { host: ADAPTER_HOST });
 
   // Launch Codex when available.
@@ -258,7 +273,7 @@ try {
   }
 
   console.log(`
-  ${status("ok", "Ready, Codex App and ChatGPT App are ready to use")}
+  ${status("ok", "Ready, Codex App is ready to use")}
 
   Adapter: ${adapterBaseUrl(ADAPTER_HOST, ADAPTER_PORT)}
 

package/package.json

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

package/src/adapter.mjs

@@ -1,5 +1,6 @@
 import http from "node:http";
 import { defaultCopilotClient } from "./copilot.mjs";
+import { buildCodexModelResponse } from "./codex-model-catalog.mjs";
 import { isValidModelList } from "./model-cache.mjs";
 import {
   ADAPTER_STATUS_PATH,
@@ -78,13 +79,58 @@ function modelListCanUseLastKnownGood(statusCode) {
   return [408, 425, 429].includes(statusCode) || statusCode >= 500;
 }
 
-function sendLastKnownGoodModels(res, modelRegistry) {
+function modelClientVersion(reqUrl) {
+  try {
+    return String(new URL(reqUrl || "/", "http://localhost").searchParams.get("client_version") || "").trim();
+  } catch {
+    return "";
+  }
+}
+
+async function sendModelList(res, models, {
+  codexModelCatalog,
+  clientVersion = "",
+  headers = {},
+  rawBody,
+  statusCode = 200,
+} = {}) {
+  let body = rawBody || JSON.stringify(models);
+  if (clientVersion && typeof codexModelCatalog?.load === "function") {
+    let response = null;
+    try {
+      const codexCatalog = await codexModelCatalog.load({ clientVersion });
+      response = buildCodexModelResponse({ copilotModels: models, codexCatalog });
+    } catch {}
+    if (!response) {
+      if (res.destroyed || res.writableEnded) return false;
+      res.writeHead(503, {
+        "Content-Type": "application/json",
+        "Retry-After": "5",
+        ...headers,
+      });
+      res.end(JSON.stringify({
+        error: {
+          message: "The Codex App model catalog is temporarily unavailable",
+          type: "server_error",
+          code: "ccdx_codex_model_catalog_unavailable",
+        },
+      }));
+      return true;
+    }
+    body = JSON.stringify(response);
+  }
+  if (res.destroyed || res.writableEnded) return false;
+  res.writeHead(statusCode, { "Content-Type": "application/json", ...headers });
+  res.end(body);
+  return true;
+}
+
+async function sendLastKnownGoodModels(res, modelRegistry, options = {}) {
   if (!isValidModelList(modelRegistry?.models) || res.destroyed || res.writableEnded) return false;
-  res.writeHead(200, {
-    "Content-Type": "application/json",
-    "X-CCDX-Model-Source": "last-known-good",
+  await sendModelList(res, modelRegistry.models, {
+    ...options,
+    headers: { "X-CCDX-Model-Source": "last-known-good" },
   });
-  res.end(JSON.stringify(modelRegistry.models));
   return true;
 }
 
@@ -100,6 +146,7 @@ export function createAdapterHandler(options = {}) {
   const responsesFn = options.responsesFn || codexClient.responses;
   const responsesCompactFn = options.responsesCompactFn || codexClient.responsesCompact;
   const listModelsFn = options.listModelsFn || codexClient.listModels;
+  const codexModelCatalog = options.codexModelCatalog;
   const getCachedModelEndpointsFn = options.getCachedModelEndpointsFn
     || codexClient.getCachedModelEndpoints;
   const codexModelRegistry = options.codexModelRegistry || options.modelRegistry;
@@ -176,10 +223,12 @@ export function createAdapterHandler(options = {}) {
     }
 
     if (req.method === "GET" && pathname === "/v1/models") {
+      const clientVersion = modelClientVersion(req.url);
       const abort = createRequestAbort(req, res);
       abort.setTimeout(upstreamTimeoutMs);
       listModelsFn({ signal: abort.signal })
-        .then(({ status, body }) => {
+        .then(async ({ status, body }) => {
+          abort.clearTimeout();
           if (status >= 200 && status < 300) {
             let models;
             try { models = JSON.parse(body); } catch {}
@@ -187,21 +236,26 @@ export function createAdapterHandler(options = {}) {
               if (codexModelRegistry) {
                 codexModelRegistry.models = models;
               }
-              res.writeHead(status, { "Content-Type": "application/json" });
-              res.end(body);
+              await sendModelList(res, models, {
+                codexModelCatalog,
+                clientVersion,
+                rawBody: body,
+                statusCode: status,
+              });
               return;
             }
-            if (sendLastKnownGoodModels(res, codexModelRegistry)) return;
+            if (await sendLastKnownGoodModels(res, codexModelRegistry, { codexModelCatalog, clientVersion })) return;
             sendJsonError(res, httpError("Copilot models response contained no valid models", 502), 502);
             return;
           }
-          if (modelListCanUseLastKnownGood(status) && sendLastKnownGoodModels(res, codexModelRegistry)) return;
+          if (modelListCanUseLastKnownGood(status)
+            && await sendLastKnownGoodModels(res, codexModelRegistry, { codexModelCatalog, clientVersion })) return;
           res.writeHead(status, { "Content-Type": "application/json" });
           res.end(body);
         })
-        .catch((e) => {
+        .catch(async (e) => {
           logRequestFailure("Models", e, abort);
-          if (sendLastKnownGoodModels(res, codexModelRegistry)) return;
+          if (await sendLastKnownGoodModels(res, codexModelRegistry, { codexModelCatalog, clientVersion })) return;
           if (!res.destroyed && !res.writableEnded) {
             if (!res.headersSent) res.writeHead(e?.statusCode || 502);
             res.end(JSON.stringify({ error: e.message }));
@@ -311,7 +365,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");
@@ -268,13 +273,14 @@ export function cliCommandName() {
 
 function topicHelp(name, topic) {
   const sections = {
-    start: `Usage:\n  ${name} [start] [--show-request-id]\n\nStarts or reuses the local adapter, updates Codex configuration, and attempts to open Codex or ChatGPT when auto-launch is enabled and supported.`,
+    start: `Usage:\n  ${name} [start] [--show-request-id]\n\nStarts or reuses the local adapter, updates Codex configuration, and attempts to open Codex App when auto-launch is enabled and supported.`,
     auth: `Usage:\n  ${name} auth status [--online] [--format table|plain]\n\nShows the saved GitHub Copilot account without exposing credentials. --online also verifies its entitlement and model catalog.`,
     "auth status": `Usage:\n  ${name} auth status [--online] [--format table|plain]\n\nShows the saved GitHub Copilot account without exposing credentials. --online also verifies its entitlement and model catalog. Interactive terminals use a table by default.`,
     doctor: `Usage:\n  ${name} doctor [--online] [--compat]\n\nChecks the local credential, Codex configuration, and adapter. --online validates account entitlement; --compat sends minimal inference requests and consumes a small amount of Copilot usage.`,
     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/codex-model-catalog.mjs

@@ -0,0 +1,261 @@
+import { execFile } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { CODEX_GPT6_MODEL } from "./models.mjs";
+
+export { CODEX_GPT6_MODEL };
+
+export const CODEX_APP_BINARY_PATHS = [
+  "/Applications/Codex.app/Contents/Resources/codex",
+  "/Applications/ChatGPT.app/Contents/Resources/codex",
+  path.join(os.homedir(), "Applications", "Codex.app", "Contents", "Resources", "codex"),
+  path.join(os.homedir(), "Applications", "ChatGPT.app", "Contents", "Resources", "codex"),
+];
+export const CODEX_MODEL_CATALOG_TIMEOUT_MS = 5_000;
+export const CODEX_MODEL_CATALOG_MAX_BUFFER = 8 * 1024 * 1024;
+export const CODEX_MODEL_CATALOG_FAILURE_BACKOFF_MS = 5_000;
+
+function objectRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function codexCatalogIsValid(catalog) {
+  if (!objectRecord(catalog) || !Array.isArray(catalog.models) || catalog.models.length === 0) return false;
+  const slugs = new Set();
+  for (const model of catalog.models) {
+    const slug = String(model?.slug || "").trim();
+    if (!objectRecord(model) || !slug || slugs.has(slug)) return false;
+    slugs.add(slug);
+  }
+  return true;
+}
+
+function copilotModelData(models) {
+  if (!objectRecord(models) || !Array.isArray(models.data) || models.data.length === 0) return null;
+  return models.data;
+}
+
+function supportsResponses(model) {
+  const endpoints = Array.isArray(model?.supported_endpoints) ? model.supported_endpoints : [];
+  return endpoints.includes("/responses") || endpoints.includes("/v1/responses");
+}
+
+function isEligibleOpenAIModel(model, id) {
+  const vendor = String(model?.vendor || model?.owned_by || "").trim().toLowerCase();
+  return String(model?.id || "").trim() === id
+    && vendor === "openai"
+    && String(model?.policy?.state || "").trim().toLowerCase() === "enabled"
+    && model?.model_picker_enabled === true
+    && supportsResponses(model);
+}
+
+export function isEligibleCopilotGpt6(copilotModels) {
+  const data = copilotModelData(copilotModels);
+  if (!data) return false;
+  const matches = data.filter((model) => String(model?.id || "").trim() === CODEX_GPT6_MODEL);
+  return matches.length === 1 && isEligibleOpenAIModel(matches[0], CODEX_GPT6_MODEL);
+}
+
+export function buildCodexModelResponse({ copilotModels, codexCatalog } = {}) {
+  if (!copilotModelData(copilotModels) || !codexCatalogIsValid(codexCatalog)) return null;
+
+  const exposeGpt6 = isEligibleCopilotGpt6(copilotModels);
+  const models = codexCatalog.models.map((model) => {
+    if (model.slug !== CODEX_GPT6_MODEL) return model;
+    if (!exposeGpt6) return { ...model, visibility: "hide" };
+    const patched = {
+      ...model,
+      visibility: "list",
+      additional_speed_tiers: [],
+      service_tiers: [],
+    };
+    delete patched.default_service_tier;
+    return patched;
+  });
+
+  return { ...copilotModels, object: copilotModels.object || "list", models };
+}
+
+function binaryCacheKey(binaryPath, stats) {
+  return [
+    binaryPath,
+    stats.dev,
+    stats.ino,
+    stats.size,
+    stats.mtimeMs,
+    stats.ctimeMs,
+  ].map((part) => String(part ?? "")).join(":");
+}
+
+async function installedCodexBinaries(binaryPaths, statFn) {
+  const installed = [];
+  for (const binaryPath of binaryPaths) {
+    let stats;
+    try {
+      stats = await statFn(binaryPath);
+    } catch {
+      continue;
+    }
+    if (stats && typeof stats.isFile === "function" && stats.isFile()) {
+      installed.push({ binaryPath, key: binaryCacheKey(binaryPath, stats) });
+    }
+  }
+  return installed;
+}
+
+function runCodexCommand(execFileFn, binaryPath, args, options) {
+  return new Promise((resolve, reject) => {
+    try {
+      execFileFn(binaryPath, args, options, (error, stdout) => {
+        if (error) reject(error);
+        else resolve(stdout);
+      });
+    } catch (error) {
+      reject(error);
+    }
+  });
+}
+
+function parsedCodexVersion(stdout) {
+  const match = /^(?:codex-cli|codex)\s+(\S+)$/.exec(String(stdout).trim());
+  return match?.[1] || null;
+}
+
+function wholeSemver(value) {
+  const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.exec(String(value || "").trim());
+  if (!match) return null;
+  if (match[4]?.split(".").some((part) => /^\d+$/.test(part) && part.length > 1 && part.startsWith("0"))) {
+    return null;
+  }
+  return `${match[1]}.${match[2]}.${match[3]}`;
+}
+
+function normalizedBackoff(value) {
+  return Number.isFinite(value) && value >= 0 ? value : CODEX_MODEL_CATALOG_FAILURE_BACKOFF_MS;
+}
+
+export function createCodexModelCatalog({
+  binaryPath,
+  execFileFn = execFile,
+  statFn = fs.promises.stat,
+  timeoutMs = CODEX_MODEL_CATALOG_TIMEOUT_MS,
+  maxBuffer = CODEX_MODEL_CATALOG_MAX_BUFFER,
+  failureBackoffMs = CODEX_MODEL_CATALOG_FAILURE_BACKOFF_MS,
+  now = Date.now,
+} = {}) {
+  const binaryPaths = binaryPath === undefined
+    ? CODEX_APP_BINARY_PATHS
+    : [binaryPath].filter((candidate) => typeof candidate === "string" && path.isAbsolute(candidate));
+  const commandOptions = {
+    encoding: "utf8",
+    maxBuffer,
+    timeout: timeoutMs,
+    windowsHide: true,
+  };
+  const backoffMs = normalizedBackoff(failureBackoffMs);
+  const versionCache = new Map();
+  const versionFailures = new Map();
+  const versionPending = new Map();
+  const catalogCache = new Map();
+  const catalogFailures = new Map();
+  const catalogPending = new Map();
+  let activeBinaryKeys = new Set();
+
+  function retainCurrentEntries(map) {
+    for (const key of map.keys()) {
+      if (!activeBinaryKeys.has(key)) map.delete(key);
+    }
+  }
+
+  async function probeVersion(candidate) {
+    if (versionCache.has(candidate.key)) return versionCache.get(candidate.key);
+    const failure = versionFailures.get(candidate.key);
+    if (failure && now() < failure.retryAt) return null;
+    if (versionPending.has(candidate.key)) return versionPending.get(candidate.key);
+
+    const promise = (async () => {
+      try {
+        const stdout = await runCodexCommand(execFileFn, candidate.binaryPath, ["--version"], commandOptions);
+        const version = wholeSemver(parsedCodexVersion(stdout));
+        if (!version) throw new Error("Invalid Codex version output");
+        if (activeBinaryKeys.has(candidate.key)) {
+          versionCache.set(candidate.key, version);
+          versionFailures.delete(candidate.key);
+        }
+        return version;
+      } catch {
+        if (activeBinaryKeys.has(candidate.key)) {
+          versionFailures.set(candidate.key, { retryAt: now() + backoffMs });
+        }
+        return null;
+      }
+    })();
+    versionPending.set(candidate.key, promise);
+    try {
+      return await promise;
+    } finally {
+      if (versionPending.get(candidate.key) === promise) versionPending.delete(candidate.key);
+    }
+  }
+
+  async function selectBinary(clientVersion) {
+    const installed = await installedCodexBinaries(binaryPaths, statFn);
+    activeBinaryKeys = new Set(installed.map((candidate) => candidate.key));
+    for (const map of [versionCache, versionFailures, catalogCache, catalogFailures]) {
+      retainCurrentEntries(map);
+    }
+    if (installed.length === 0) return null;
+    const rawVersion = String(clientVersion || "").trim();
+    if (!rawVersion) return installed[0];
+    const expectedVersion = wholeSemver(rawVersion);
+    if (!expectedVersion) return null;
+    for (const candidate of installed) {
+      if (await probeVersion(candidate) === expectedVersion) return candidate;
+    }
+    return null;
+  }
+
+  async function loadCatalog(candidate) {
+    if (catalogCache.has(candidate.key)) return catalogCache.get(candidate.key);
+    const failure = catalogFailures.get(candidate.key);
+    if (failure && now() < failure.retryAt) return null;
+    if (catalogPending.has(candidate.key)) return catalogPending.get(candidate.key);
+
+    const promise = (async () => {
+      try {
+        const stdout = await runCodexCommand(
+          execFileFn,
+          candidate.binaryPath,
+          ["debug", "models", "--bundled"],
+          commandOptions,
+        );
+        const catalog = JSON.parse(String(stdout));
+        if (!codexCatalogIsValid(catalog)) throw new Error("Invalid Codex model catalog");
+        if (activeBinaryKeys.has(candidate.key)) {
+          catalogCache.set(candidate.key, catalog);
+          catalogFailures.delete(candidate.key);
+        }
+        return catalog;
+      } catch {
+        if (activeBinaryKeys.has(candidate.key)) {
+          catalogFailures.set(candidate.key, { retryAt: now() + backoffMs });
+        }
+        return null;
+      }
+    })();
+    catalogPending.set(candidate.key, promise);
+    try {
+      return await promise;
+    } finally {
+      if (catalogPending.get(candidate.key) === promise) catalogPending.delete(candidate.key);
+    }
+  }
+
+  async function load({ clientVersion = "" } = {}) {
+    const candidate = await selectBinary(clientVersion);
+    return candidate ? loadCatalog(candidate) : null;
+  }
+
+  return { load };
+}

package/src/launcher.mjs

@@ -3,8 +3,7 @@ import { status } from "./status.mjs";
 
 export { ensureAuth } from "./auth.mjs";
 
-// Prefer the Codex bundle identifier, then fall back to the known app paths.
-// This supports both Codex.app and ChatGPT.app regardless of installation path.
+// Prefer the Codex bundle identifier, then fall back to its known app paths.
 const CODEX_BUNDLE_ID = "com.openai.codex";
 const APP_PATH_CANDIDATES = [
   "/Applications/Codex.app",
@@ -40,12 +39,12 @@ export function launchAttempts() {
 export async function openCodex({ env = process.env, spawnImpl = spawn, platform = process.platform } = {}) {
   if (platform !== "darwin") {
     console.log(status("warn", "Auto-launch is only supported on macOS"));
-    console.log(status("info", "Open Codex or the ChatGPT app manually; it will connect to the adapter."));
+    console.log(status("info", "Open Codex App manually; it will connect to the adapter."));
     return false;
   }
 
   if (!autoLaunchEnabled(env)) {
-    console.log(status("info", "Auto-launch disabled (CCDX_AUTO_LAUNCH=0); open Codex or the ChatGPT app manually."));
+    console.log(status("info", "Auto-launch disabled (CCDX_AUTO_LAUNCH=0); open Codex App manually."));
     return false;
   }
 
@@ -57,7 +56,7 @@ export async function openCodex({ env = process.env, spawnImpl = spawn, platform
   }
 
   console.log(status("warn", "Could not launch the Codex app (checked com.openai.codex, Codex.app, ChatGPT.app)"));
-  console.log(status("info", "Open Codex or the ChatGPT app manually; it will connect to the adapter."));
+  console.log(status("info", "Open Codex App manually; it will connect to the adapter."));
   console.log(status("info", "Download it from https://openai.com/codex"));
   return false;
 }

package/src/models.mjs

@@ -1,5 +1,6 @@
 export const CODEX_AUTO_REVIEW_MODEL = "codex-auto-review";
 export const DEFAULT_CODEX_AUTO_REVIEW_MODEL = "gpt-5.5";
+export const CODEX_GPT6_MODEL = "gpt-6-astra";
 
 function hasOpenAIEndpoint(model) {
   const endpoints = Array.isArray(model?.supported_endpoints) ? model.supported_endpoints : [];

package/src/responses-handler.mjs

@@ -12,6 +12,7 @@ import {
   writeOrDrain,
 } from "./http-transport.mjs";
 import {
+  CODEX_GPT6_MODEL,
   CODEX_AUTO_REVIEW_MODEL,
   modelIsResponsesOnly,
   modelSupportsChatCompletions,
@@ -87,6 +88,14 @@ function resolveRequestModel(model, openAIModelEnv, autoReviewModelResolver) {
   return resolveOpenAIModel(model, openAIModelEnv, options);
 }
 
+function stripUnsupportedGpt6ServiceTier(body, requestedModel, upstreamModel) {
+  if (requestedModel === CODEX_GPT6_MODEL
+    && upstreamModel === requestedModel
+    && body.service_tier === "priority") {
+    delete body.service_tier;
+  }
+}
+
 export function createResponsesHandler(options) {
   const {
     acquireRequest,
@@ -216,6 +225,7 @@ export function createResponsesHandler(options) {
         upstreamModel = priorityTierModel;
         delete prepared.body.service_tier;
       }
+      stripUnsupportedGpt6ServiceTier(prepared.body, requestedModel, upstreamModel);
       if (requestedModel === CODEX_AUTO_REVIEW_MODEL) delete prepared.body.service_tier;
       if (upstreamModel !== requestedModel) prepared.body.model = upstreamModel;
       const upstreamLog = upstreamModel === requestedModel ? "" : ` upstream_model=${upstreamModel}`;
@@ -465,6 +475,7 @@ export function createResponsesCompactHandler(options) {
         upstreamModel = priorityTierModel;
         delete prepared.body.service_tier;
       }
+      stripUnsupportedGpt6ServiceTier(prepared.body, requestedModel, upstreamModel);
       if (requestedModel === CODEX_AUTO_REVIEW_MODEL) delete prepared.body.service_tier;
       if (upstreamModel !== requestedModel) prepared.body.model = upstreamModel;
       const upstreamLog = upstreamModel === requestedModel ? "" : ` upstream_model=${upstreamModel}`;

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 };
+}