talon-agent 5.2.2 → 5.4.0

package/src/cli/commands/backup.ts

@@ -0,0 +1,396 @@
+/**
+ * `talon backup` — snapshots and checkpoints from the outside.
+ *
+ * Two execution modes, chosen per subcommand:
+ *
+ *   - Through the daemon (`now`, `targets`, `status`) when one is
+ *     running. The daemon has the plugins loaded, so it is the only
+ *     process that can see the remote targets — and routing through it
+ *     also means one writer, not two racing `VACUUM INTO`s.
+ *   - In this process (`list`, `show`, `pin`, `unpin`, `prune`, and
+ *     `now` with no daemon) — they read the manifests on disk and the
+ *     index in talon.db, both of which are safe to touch concurrently.
+ *
+ * `restore` refuses while the daemon is running, full stop: it replaces
+ * the database and the memory under a live process. Stop Talon first, or
+ * use `/backup restore <id>` from chat, which stages the request and
+ * lets the next boot apply it before anything opens the database.
+ *
+ * Lives in `commands/` because that is where docs/structure.md's worklist
+ * item 8 puts every CLI command; `src/cli/` itself is at its file ceiling.
+ */
+
+import pc from "picocolors";
+import { createInterface } from "node:readline/promises";
+import { getFrontends, loadConfig } from "../../core/config/index.js";
+import { findRunningInstance } from "../../core/daemon/discovery.js";
+import {
+  collectBackupStatus,
+  formatBackupStatus,
+  formatBytes,
+  formatRelative,
+  isSnapshotId,
+  listSnapshots,
+  discoverTargets,
+  readManifest,
+  restoreSnapshot,
+  setSnapshotPinned,
+  type BackupTarget,
+  type SnapshotSummary,
+} from "../../core/backup/index.js";
+import { resolveBackupSettings } from "../../core/backup/plan.js";
+import { buildSnapshot } from "../../core/backup/snapshot.js";
+import { pruneLocal } from "../../core/backup/store.js";
+import { fetchGateway } from "../daemon-api.js";
+
+const USAGE = `
+  ${pc.bold("talon backup")} — snapshots and checkpoints
+
+    ${pc.cyan("now")} [--checkpoint <label>] [--pin]   take a snapshot now
+    ${pc.cyan("list")} [--remote <targetId>]           list snapshots
+    ${pc.cyan("show")} <id>                            everything about one snapshot
+    ${pc.cyan("pin")} <id>  |  ${pc.cyan("unpin")} <id>          keep past retention, or release
+    ${pc.cyan("restore")} <id> [--from <target>] [--yes]  restore (daemon must be stopped)
+    ${pc.cyan("prune")}                                apply the local retention policy
+    ${pc.cyan("targets")}                              remote targets and their readiness
+    ${pc.cyan("status")}                               schedule, sizes, targets
+`;
+
+type Flags = { values: string[]; flags: Map<string, string | true> };
+
+/** `--from drive --yes x` → { values: ["x"], flags: { from: "drive", yes: true } } */
+function parseArgs(argv: readonly string[]): Flags {
+  const values: string[] = [];
+  const flags = new Map<string, string | true>();
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (!arg.startsWith("--")) {
+      values.push(arg);
+      continue;
+    }
+    const name = arg.slice(2);
+    const next = argv[i + 1];
+    if (next && !next.startsWith("--")) {
+      flags.set(name, next);
+      i++;
+    } else {
+      flags.set(name, true);
+    }
+  }
+  return { values, flags };
+}
+
+async function daemonPort(): Promise<number | null> {
+  const instance = await findRunningInstance();
+  return instance?.port ?? null;
+}
+
+/** Run one action inside the daemon. Returns null when there is no daemon. */
+async function viaDaemon(
+  body: Record<string, unknown>,
+): Promise<{ ok: boolean; text?: string; error?: string } | null> {
+  const port = await daemonPort();
+  if (port === null) return null;
+  // A snapshot of a large workspace can take minutes; the default CLI
+  // budget is three seconds.
+  return (await fetchGateway(
+    port,
+    "/action",
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    },
+    15 * 60_000,
+  )) as { ok: boolean; text?: string; error?: string };
+}
+
+function renderResult(result: {
+  ok: boolean;
+  text?: string;
+  error?: string;
+}): void {
+  if (result.ok) console.log(`  ${result.text ?? "Done."}\n`);
+  else console.log(`  ${pc.red("●")} ${result.error ?? "Failed."}\n`);
+}
+
+function renderRow(snapshot: SnapshotSummary): string {
+  const marks = [
+    snapshot.kind === "checkpoint"
+      ? pc.magenta("checkpoint")
+      : pc.dim("backup"),
+    snapshot.pinned ? pc.yellow("pinned") : "",
+    snapshot.local ? "" : pc.dim("(remote only)"),
+  ].filter(Boolean);
+  const remote = Object.entries(snapshot.remote)
+    .map(([id, entry]) =>
+      entry.status === "uploaded"
+        ? pc.green(id)
+        : pc.yellow(`${id}:${entry.status}`),
+    )
+    .join(" ");
+  return (
+    `  ${pc.bold(snapshot.id)}  ${marks.join(" ")}  ${formatBytes(snapshot.sizeBytes).padStart(9)}` +
+    `  ${pc.dim(formatRelative(snapshot.createdAt))}` +
+    (snapshot.label ? `  ${snapshot.label}` : "") +
+    (remote ? `  → ${remote}` : "")
+  );
+}
+
+// ── Subcommands ─────────────────────────────────────────────────────────────
+
+async function backupNow(flags: Flags): Promise<void> {
+  const label =
+    typeof flags.flags.get("checkpoint") === "string"
+      ? String(flags.flags.get("checkpoint"))
+      : undefined;
+  const pin = flags.flags.get("pin") === true;
+  const remote = await viaDaemon({ action: "backup.now", label, pin });
+  if (remote) {
+    renderResult(remote);
+    return;
+  }
+  console.log(
+    `  ${pc.dim("Talon is not running — taking a local snapshot (no remote upload).")}`,
+  );
+  const settings = resolveBackupSettings(loadConfig().backup);
+  const manifest = await buildSnapshot({
+    kind: label ? "checkpoint" : "backup",
+    label,
+    pinned: pin,
+    settings,
+  });
+  await pruneLocal(settings.keepLocal);
+  console.log(
+    `  ${pc.green("●")} ${manifest.id} — ${manifest.parts.length} part(s), ` +
+      `${formatBytes(manifest.sizeBytes)}\n`,
+  );
+}
+
+async function backupList(flags: Flags): Promise<void> {
+  const target = flags.flags.get("remote");
+  const snapshots = await listSnapshots();
+  const filtered =
+    typeof target === "string"
+      ? snapshots.filter(
+          (snapshot) => snapshot.remote[target]?.status === "uploaded",
+        )
+      : snapshots;
+  if (filtered.length === 0) {
+    console.log(`  ${pc.dim("No snapshots.")}\n`);
+    return;
+  }
+  console.log("");
+  for (const snapshot of filtered) console.log(renderRow(snapshot));
+  const bytes = filtered.reduce((sum, snapshot) => sum + snapshot.sizeBytes, 0);
+  console.log(
+    `\n  ${pc.dim(`${filtered.length} snapshot(s), ${formatBytes(bytes)}`)}\n`,
+  );
+}
+
+async function backupShow(id: string): Promise<void> {
+  const manifest = await readManifest(id);
+  if (!manifest) {
+    console.log(`  ${pc.red("●")} No snapshot ${id} on this machine.\n`);
+    return;
+  }
+  console.log(
+    `\n  ${pc.bold(manifest.id)}  ${manifest.kind}${manifest.pinned ? pc.yellow(" pinned") : ""}`,
+  );
+  if (manifest.label) console.log(`  ${manifest.label}`);
+  console.log(
+    `  taken     ${new Date(manifest.createdAt).toISOString()} (${formatRelative(manifest.createdAt)})`,
+  );
+  console.log(
+    `  host      ${manifest.host}  talon ${manifest.talonVersion}${manifest.gitHead ? ` @ ${manifest.gitHead}` : ""}`,
+  );
+  console.log(`  size      ${formatBytes(manifest.sizeBytes)}`);
+  console.log(
+    `  parts     ${manifest.parts.map((part) => `${part.name} (${formatBytes(part.bytes)})`).join(", ")}`,
+  );
+  console.log(`  includes  ${manifest.includes.join(", ")}`);
+  if (manifest.extras?.length) {
+    console.log(
+      `  extras    ${manifest.extras.map((extra) => `extra/${extra.n} ← ${extra.source}`).join(", ")}`,
+    );
+  }
+  for (const [targetId, state] of Object.entries(manifest.remote)) {
+    console.log(
+      `  remote    ${targetId}: ${state.status}${state.error ? ` — ${state.error}` : ""}`,
+    );
+  }
+  console.log("");
+}
+
+async function backupPin(id: string, pinned: boolean): Promise<void> {
+  const ok = await setSnapshotPinned(id, pinned);
+  console.log(
+    ok
+      ? `  ${pc.green("●")} ${id} is ${pinned ? "pinned — retention will never prune it" : "unpinned"}\n`
+      : `  ${pc.red("●")} No snapshot ${id}\n`,
+  );
+}
+
+async function backupPrune(): Promise<void> {
+  const settings = resolveBackupSettings(loadConfig().backup);
+  const removed = await pruneLocal(settings.keepLocal);
+  console.log(
+    removed.length === 0
+      ? `  ${pc.dim(`Nothing to prune (keepLocal=${settings.keepLocal}).`)}\n`
+      : `  ${pc.green("●")} Pruned ${removed.length}: ${removed.join(", ")}\n`,
+  );
+}
+
+async function backupTargets(): Promise<void> {
+  const result = await viaDaemon({ action: "backup.status" });
+  if (!result) {
+    console.log(
+      `  ${pc.yellow("●")} Talon is not running — remote targets live in the daemon's plugins.\n`,
+    );
+    return;
+  }
+  renderResult(result);
+}
+
+async function backupStatus(): Promise<void> {
+  const result = await viaDaemon({ action: "backup.status" });
+  if (result) {
+    renderResult(result);
+    return;
+  }
+  const status = await collectBackupStatus({ withTargets: false });
+  console.log(
+    `\n${formatBackupStatus(status)
+      .split("\n")
+      .map((line) => `  ${line}`)
+      .join("\n")}\n`,
+  );
+}
+
+async function confirm(question: string): Promise<boolean> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return (await rl.question(question)).trim().toLowerCase() === "yes";
+  } finally {
+    rl.close();
+  }
+}
+
+async function backupRestore(id: string, flags: Flags): Promise<void> {
+  if (!isSnapshotId(id)) {
+    console.log(`  ${pc.red("●")} "${id}" is not a snapshot id.\n`);
+    return;
+  }
+  const instance = await findRunningInstance();
+  if (instance) {
+    console.log(
+      `  ${pc.red("●")} Talon is running (PID ${instance.pid}). A restore replaces the\n` +
+        `    database and memory underneath it. Run ${pc.cyan("talon stop")} first, or use\n` +
+        `    ${pc.cyan(`/backup restore ${id}`)} from chat — that stages the restore and applies\n` +
+        `    it during the next boot.\n`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+  const manifest = await readManifest(id);
+  const from = flags.flags.get("from");
+  if (!manifest && typeof from !== "string") {
+    console.log(
+      `  ${pc.red("●")} No snapshot ${id} on this machine (use --from <target> to fetch it).\n`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+  if (flags.flags.get("yes") !== true) {
+    console.log(
+      `\n  This replaces config, prompts, keys, sessions, the database and memory\n` +
+        `  with the contents of ${pc.bold(id)}${manifest?.label ? ` ("${manifest.label}")` : ""}.\n` +
+        `  A pinned checkpoint of the current state is taken first.\n`,
+    );
+    if (!(await confirm(`  Type ${pc.bold("yes")} to continue: `))) {
+      console.log(`  ${pc.dim("Cancelled.")}\n`);
+      return;
+    }
+  }
+  const settings = resolveBackupSettings(loadConfig().backup);
+  const target =
+    typeof from === "string" ? await resolveTarget(from) : undefined;
+  const report = await restoreSnapshot({ id, settings, target });
+  const written = Object.entries(report.written)
+    .map(([root, count]) => `${root} (${count})`)
+    .join(", ");
+  console.log(`\n  ${pc.green("●")} Restored ${report.id}`);
+  if (report.checkpointId) {
+    console.log(
+      `  Previous state saved as ${pc.bold(report.checkpointId)} (pinned).`,
+    );
+  }
+  console.log(`  Written: ${written || "nothing"}`);
+  console.log(`  Removed: ${report.removed} file(s)`);
+  console.log(
+    `  Database: ${report.databaseReplaced ? "replaced" : "left in place"}\n`,
+  );
+}
+
+/**
+ * Find a target by id. Targets are plugins, and a restore runs with the
+ * daemon stopped, so this process loads them itself — the same call
+ * bootstrap makes, minus the frontends.
+ */
+async function resolveTarget(id: string): Promise<BackupTarget | undefined> {
+  const config = loadConfig();
+  const { loadPlugins } = await import("../../core/plugin/index.js");
+  await loadPlugins(config.plugins, getFrontends(config));
+  const targets = await discoverTargets();
+  const target = targets.find((candidate) => candidate.id === id);
+  if (!target) {
+    console.log(
+      `  ${pc.red("●")} No backup target "${id}"` +
+        (targets.length > 0
+          ? ` — loaded: ${targets.map((t) => t.id).join(", ")}\n`
+          : " — no target plugins are configured.\n"),
+    );
+  }
+  return target;
+}
+
+// ── Entry ───────────────────────────────────────────────────────────────────
+
+export async function runBackupCommand(argv: readonly string[]): Promise<void> {
+  const { values, flags } = parseArgs(argv);
+  const [subcommand, id] = values;
+  const args: Flags = { values, flags };
+  switch (subcommand) {
+    case "now":
+      await backupNow(args);
+      return;
+    case "list":
+      await backupList(args);
+      return;
+    case "show":
+      if (!id) return void console.log(USAGE);
+      await backupShow(id);
+      return;
+    case "pin":
+    case "unpin":
+      if (!id) return void console.log(USAGE);
+      await backupPin(id, subcommand === "pin");
+      return;
+    case "restore":
+      if (!id) return void console.log(USAGE);
+      await backupRestore(id, args);
+      return;
+    case "prune":
+      await backupPrune();
+      return;
+    case "targets":
+      await backupTargets();
+      return;
+    case "status":
+    case undefined:
+      await backupStatus();
+      return;
+    default:
+      console.log(USAGE);
+  }
+}

package/src/cli/config-view.ts

@@ -54,6 +54,7 @@ export async function viewConfig(): Promise<void> {
     kilo: "Kilo (@kilocode/sdk)",
     opencode: "OpenCode (@opencode-ai/sdk)",
     codex: "OpenAI Codex CLI",
+    agy: "Google Antigravity CLI",
     "openai-agents": "OpenAI Agents (@openai/agents)",
   };
   console.log(
@@ -63,6 +64,10 @@ export async function viewConfig(): Promise<void> {
     console.log(
       `  ${pc.dim("Claude binary")}    ${pc.green(config.claudeBinary)}`,
     );
+  if (config.agyBinary)
+    console.log(
+      `  ${pc.dim("Antigravity bin")}  ${pc.green(config.agyBinary)}`,
+    );
   if (config.codexApiKey)
     console.log(
       `  ${pc.dim("Codex API key")}    ${maskToken(config.codexApiKey)}`,

package/src/cli/config.ts

@@ -27,10 +27,12 @@ export function printBanner(): void {
  */
 export type Config = {
   frontend: string | string[];
-  /** Active backend (`claude` / `kilo` / `opencode` / `codex` / `openai-agents`). */
-  backend?: "claude" | "kilo" | "opencode" | "codex" | "openai-agents";
+  /** Active backend (`claude` / `kilo` / `opencode` / `codex` / `agy` / `openai-agents`). */
+  backend?: "claude" | "kilo" | "opencode" | "codex" | "agy" | "openai-agents";
   botToken?: string;
   claudeBinary?: string;
+  /** Path to the Antigravity `agy` executable. */
+  agyBinary?: string;
   /** Codex-specific OpenAI API key. */
   codexApiKey?: string;
   /** OpenAI API key — used by OpenAI Agents and legacy Codex config. */

package/src/cli/events.ts

@@ -44,6 +44,20 @@ function describe(event: TalonEvent): string {
       return `${event.agentId} "${event.label}" → ${event.state} (${event.durationMs}ms)`;
     case "agent.message":
       return `${event.from} → ${event.to} (${event.kind})`;
+    case "backup.started":
+      return `${event.kind} (${event.trigger})`;
+    case "backup.completed":
+      return (
+        `${event.snapshotId} ${event.kind} ${event.parts} part(s) ` +
+        `${(event.sizeBytes / 1024 / 1024).toFixed(1)}MB (${event.durationMs}ms)`
+      );
+    case "backup.failed":
+      return `${event.trigger} failed (streak ${event.consecutiveFailures}): ${event.error}`;
+    case "backup.uploaded":
+      return (
+        `${event.snapshotId} → ${event.targetId} ` +
+        `${(event.bytes / 1024 / 1024).toFixed(1)}MB${event.deduplicated ? " (deduplicated)" : ""}`
+      );
   }
 }
 

package/src/cli/index.ts

@@ -14,6 +14,8 @@
  *   - `chat`        — terminal chat mode
  *   - `daemon`      — start/stop/restart outcome rendering
  *   - `menu`        — interactive main menu (no-subcommand default)
+ *   - `commands/`   — one module per command; new commands land here
+ *                     (docs/structure.md worklist item 8)
  */
 
 import pc from "picocolors";
@@ -36,6 +38,7 @@ import { runPluginCommand } from "./plugin.js";
 import { runSkillCommand } from "./skill.js";
 import { runMemoryCommand } from "./memory.js";
 import { mainMenu } from "./menu.js";
+import { runBackupCommand } from "./commands/backup.js";
 
 export * from "./context.js";
 export * from "./config.js";
@@ -58,8 +61,63 @@ const CLI_COMMANDS = [
   "plugin",
   "skill",
   "memory",
+  "backup",
 ];
 
+/** `talon events [-f] [--history [N]]` → the tail options. */
+function eventsOptions(args: string[]): {
+  follow: boolean;
+  history?: number;
+} {
+  const historyAt = args.findIndex((a) => a === "--history");
+  const next = historyAt >= 0 ? Number(args[historyAt + 1]) : NaN;
+  return {
+    follow: args.includes("-f") || args.includes("--follow"),
+    ...(historyAt >= 0
+      ? { history: Number.isInteger(next) && next > 0 ? next : 100 }
+      : {}),
+  };
+}
+
+/** The `talon --help` sheet. Its own function: `runCli` is a router. */
+function printHelp(): void {
+  printBanner();
+  console.log("  Usage: talon [command]\n");
+  console.log("  Commands:");
+  console.log(`    ${pc.cyan("setup")}      Guided setup wizard`);
+  console.log(`    ${pc.cyan("start")}      Start as background daemon`);
+  console.log(`    ${pc.cyan("stop")}       Stop the daemon`);
+  console.log(`    ${pc.cyan("restart")}    Restart the daemon`);
+  console.log(`    ${pc.cyan("run")}        Run in foreground (attached)`);
+  console.log(`    ${pc.cyan("chat")}       Terminal chat mode`);
+  console.log(`    ${pc.cyan("status")}     Show bot health`);
+  console.log(
+    `    ${pc.cyan("ps")}         List agent tasks (--all includes journal history)`,
+  );
+  console.log(`    ${pc.cyan("kill")}       Abort a killable task by id`);
+  console.log(
+    `    ${pc.cyan("events")}     Tail the event bus (-f follows, --history [N] reads the journal)`,
+  );
+  console.log(
+    `    ${pc.cyan("plugin")}     Manage plugins (install/enable/disable)`,
+  );
+  console.log(
+    `    ${pc.cyan("skill")}      Manage skills (install/enable/disable)`,
+  );
+  console.log(
+    `    ${pc.cyan("memory")}     Read/edit the memory store (list/search/import/render)`,
+  );
+  console.log(
+    `    ${pc.cyan("backup")}     Snapshots and checkpoints (now/list/show/pin/restore)`,
+  );
+  console.log(`    ${pc.cyan("config")}     View/edit configuration`);
+  console.log(`    ${pc.cyan("logs")}       Tail log file`);
+  console.log(`    ${pc.cyan("doctor")}     Validate environment`);
+  console.log(`    ${pc.cyan("--version")}  Print the package version`);
+  console.log();
+  console.log(`  Run ${pc.cyan("talon")} with no args for interactive menu.\n`);
+}
+
 /** Route a `talon <command>` invocation. Called by the entry point. */
 export async function runCli(): Promise<void> {
   const command = process.argv[2];
@@ -105,18 +163,12 @@ export async function runCli(): Promise<void> {
     case "kill":
       await killTask(process.argv[3]);
       break;
-    case "events": {
-      const args = process.argv.slice(3);
-      const historyAt = args.findIndex((a) => a === "--history");
-      const next = historyAt >= 0 ? Number(args[historyAt + 1]) : NaN;
-      await showEvents({
-        follow: args.includes("-f") || args.includes("--follow"),
-        ...(historyAt >= 0
-          ? { history: Number.isInteger(next) && next > 0 ? next : 100 }
-          : {}),
-      });
+    case "events":
+      await showEvents(eventsOptions(process.argv.slice(3)));
+      break;
+    case "backup":
+      await runBackupCommand(process.argv.slice(3));
       break;
-    }
     case "plugin":
       await runPluginCommand(process.argv.slice(3));
       break;
@@ -133,40 +185,7 @@ export async function runCli(): Promise<void> {
     }
     case "--help":
     case "-h":
-      printBanner();
-      console.log("  Usage: talon [command]\n");
-      console.log("  Commands:");
-      console.log(`    ${pc.cyan("setup")}      Guided setup wizard`);
-      console.log(`    ${pc.cyan("start")}      Start as background daemon`);
-      console.log(`    ${pc.cyan("stop")}       Stop the daemon`);
-      console.log(`    ${pc.cyan("restart")}    Restart the daemon`);
-      console.log(`    ${pc.cyan("run")}        Run in foreground (attached)`);
-      console.log(`    ${pc.cyan("chat")}       Terminal chat mode`);
-      console.log(`    ${pc.cyan("status")}     Show bot health`);
-      console.log(
-        `    ${pc.cyan("ps")}         List agent tasks (--all includes journal history)`,
-      );
-      console.log(`    ${pc.cyan("kill")}       Abort a killable task by id`);
-      console.log(
-        `    ${pc.cyan("events")}     Tail the event bus (-f follows, --history [N] reads the journal)`,
-      );
-      console.log(
-        `    ${pc.cyan("plugin")}     Manage plugins (install/enable/disable)`,
-      );
-      console.log(
-        `    ${pc.cyan("skill")}      Manage skills (install/enable/disable)`,
-      );
-      console.log(
-        `    ${pc.cyan("memory")}     Read/edit the memory store (list/search/import/render)`,
-      );
-      console.log(`    ${pc.cyan("config")}     View/edit configuration`);
-      console.log(`    ${pc.cyan("logs")}       Tail log file`);
-      console.log(`    ${pc.cyan("doctor")}     Validate environment`);
-      console.log(`    ${pc.cyan("--version")}  Print the package version`);
-      console.log();
-      console.log(
-        `  Run ${pc.cyan("talon")} with no args for interactive menu.\n`,
-      );
+      printHelp();
       break;
     case undefined:
       mainMenu();

package/src/cli/setup.ts

@@ -6,6 +6,8 @@
 import * as p from "@clack/prompts";
 import pc from "picocolors";
 import { printBanner, loadConfig, saveConfig, type Config } from "./config.js";
+import { binaryOnPath } from "../util/binary-on-path.js";
+import { detectAgyAuth } from "../backend/agy/auth.js";
 
 /** Strip spaces, "+", brackets and dashes from a phone number. */
 const bareDigits = (raw: string) => raw.replace(/[\s+()-]/g, "");
@@ -393,6 +395,10 @@ async function askBackend(config: Config): Promise<Config["backend"]> {
           value: "codex",
           label: `Codex     ${pc.dim("— OpenAI Codex CLI (@openai/codex)")}`,
         },
+        {
+          value: "agy",
+          label: `Antigravity ${pc.dim("— Google Antigravity CLI (agy, subscription OAuth)")}`,
+        },
         {
           value: "openai-agents",
           label: `OpenAI Agents ${pc.dim("— @openai/agents (OpenAI or any OpenAI-compatible endpoint)")}`,
@@ -405,6 +411,7 @@ async function askBackend(config: Config): Promise<Config["backend"]> {
 type BackendAnswers = Pick<
   SetupAnswers,
   | "claudeBinary"
+  | "agyBinary"
   | "codexApiKey"
   | "openaiApiKey"
   | "openaiBaseUrl"
@@ -434,6 +441,44 @@ async function askCodexBackend(config: Config): Promise<BackendAnswers> {
   return { codexApiKey: trimmedOrUndefined(codexApiKey) };
 }
 
+/**
+ * Antigravity has no API key to collect — it authenticates through a
+ * consumer Google OAuth flow run once interactively, cached under
+ * `~/.gemini/antigravity-cli/`. All the wizard can usefully do is
+ * point at the binary and say where the login happens.
+ */
+async function askAgyBackend(config: Config): Promise<BackendAnswers> {
+  const binary = await askOrExit(
+    p.text({
+      message: "Antigravity CLI binary path",
+      placeholder: "leave empty for default (agy on PATH)",
+      initialValue: config.agyBinary || "",
+    }),
+  );
+  const resolved = trimmedOrUndefined(binary);
+  const probe = resolved || "agy";
+  const installed = binaryOnPath(probe);
+  if (!installed) {
+    p.log.warn(
+      `${pc.yellow("!")} \`${probe}\` not found — install the Antigravity CLI ` +
+        `and make sure it is on PATH before starting Talon.`,
+    );
+  }
+  const auth = detectAgyAuth();
+  if (!auth.present) {
+    p.log.warn(
+      `${pc.yellow("!")} No cached Antigravity credentials. Run ${pc.cyan("agy")} ` +
+        `once on this host and complete the Google sign-in; headless runs ` +
+        `then reuse the cache. There is no API key for this backend.`,
+    );
+  } else {
+    p.log.success(
+      `Antigravity credentials found (${auth.method ?? "oauth"}) at ${auth.path}`,
+    );
+  }
+  return { agyBinary: resolved };
+}
+
 async function askOpenAiAgentsBackend(config: Config): Promise<BackendAnswers> {
   const openaiApiKey = trimmedOrUndefined(
     await askOrExit(
@@ -494,6 +539,8 @@ async function askBackendCredentials(
       return askClaudeBackend(config);
     case "codex":
       return askCodexBackend(config);
+    case "agy":
+      return askAgyBackend(config);
     case "openai-agents":
       return askOpenAiAgentsBackend(config);
     default:
@@ -553,6 +600,7 @@ export type SetupAnswers = {
   backend: Config["backend"];
   botToken?: string;
   claudeBinary?: string;
+  agyBinary?: string;
   codexApiKey?: string;
   openaiApiKey?: string;
   openaiBaseUrl?: string;
@@ -612,6 +660,7 @@ export function buildSetupConfig(
     codexApiKey: ownsCredential("codex")
       ? answers.codexApiKey
       : existing.codexApiKey,
+    agyBinary: ownsCredential("agy") ? answers.agyBinary : existing.agyBinary,
     openaiApiKey: ownsCredential("openai-agents")
       ? answers.openaiApiKey
       : existing.openaiApiKey,