codemax-cli 0.0.0-stage → 0.1.1

package/NOTICE

@@ -0,0 +1,27 @@
+codemax
+Copyright (C) 2026 Saidev Dhal <https://saidev.codes>
+
+This program is free software: you can redistribute it and/or modify it under
+the terms of the GNU Affero General Public License as published by the Free
+Software Foundation, version 3 only (AGPL-3.0-only). See LICENSE.
+
+This program is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+PARTICULAR PURPOSE. See the GNU Affero General Public License for more details.
+
+Additional permission under GNU AGPL version 3 section 7
+
+codemax works by starting and talking to coding agents and their libraries,
+some of which are distributed under their own non-free terms (for example
+Claude Code and @anthropic-ai/claude-agent-sdk, Codex, Grok, Gemini CLI,
+Cursor Agent and GitHub Copilot CLI). If you modify this program, or any
+covered work, by linking or combining it with such an agent program or library
+(or a modified version of it), the copyright holder grants you additional
+permission to convey the resulting work. Corresponding Source for the
+non-source form of such a combination shall not include the source code for
+the parts of those agent programs or libraries that are not covered by this
+License.
+
+Trademarks
+
+The AGPL covers the code, not the codemax name or logo. See TRADEMARKS.md.

package/README.md

@@ -1,3 +1,151 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="assets/logo.svg" width="360" alt="codemax" />
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center"><b>Every AI coding plan you pay for. One terminal.</b></p>
+
+<p align="center">
+  Claude Code · Codex · OpenCode · Grok · Cursor · Gemini CLI
+</p>
+
+---
+
+## What you get
+
+- **Never stop at a usage limit.** When one agent runs out, press Enter and the next one resumes the same task exactly where it stopped: same plan, the step that was in flight, and the real code changes so far.
+- **One shared task across every agent.** Every step each agent takes is recorded, so a switch is a resume, not a summary. An agent you return to is caught up on what the others did.
+- **Only the subscriptions you already pay for.** No API keys, no per-token bills, no new account.
+- **Every agent asks before acting.** Edits and commands wait for your approval, just like in each agent's own app.
+- **Undo any turn.** Roll back the files a reply changed with `/undo`.
+- **See what you're getting.** `/usage` shows tokens and their API-equivalent value per agent, with daily budgets if you want them.
+- **Free and open source.** Everything stays on your machine.
+
+```
+ ❯ fix the failing auth test
+ ⏺ Fixed the off-by-one in token expiry. 14 tests pass.
+   ⎿  Claude Code reached its daily limit · Enter to continue in Codex
+ ───────────────────── Codex · gpt-5.6-terra · new session ─────────────────────
+ ❯ now add a test for the refresh path
+ ⏺ Added refresh-expiry coverage. 15 tests pass.
+```
+
+## Get started
+
+**macOS and Linux:**
+
+```sh
+curl -fsSL https://codemax.saidev.codes/install | bash
+```
+
+**Windows** (PowerShell; Windows support is new):
+
+```powershell
+irm https://codemax.saidev.codes/install.ps1 | iex
+```
+
+It installs codemax (and [Bun](https://bun.sh) if you don't have it), then lists the agent CLIs it found. You need at least one agent you're logged in to. Then:
+
+```sh
+codemax doctor        # confirms nothing will bill an API key
+cd ~/your-project && codemax
+```
+
+It installs the latest release. Run the same command again to update. To uninstall, delete `~/.codemax/cli` and `codemax` (or `codemax.cmd` on Windows) from `~/.bun/bin`.
+
+<details>
+<summary>Install from a clone instead</summary>
+
+```sh
+git clone https://github.com/SkidGod4444/codemax-cli.git
+cd codemax-cli && bun install && bun link
+```
+
+</details>
+
+## Supported agents
+
+| Agent | Plan it uses | Status |
+|---|---|---|
+| Claude Code | Claude Pro / Max | Supported |
+| Codex | ChatGPT Plus / Pro | Supported |
+| OpenCode | Your OpenCode login | Supported |
+| Grok | SuperGrok | Supported |
+| Cursor Agent | Cursor plans | Supported (needs Cursor Agent 2026.10 or newer). Changing its model with `/model` also changes Cursor's own default. |
+| Gemini CLI | Google AI plans | Early, untested |
+| Copilot CLI | GitHub Copilot plans | In its own UI via `codemax --tui` |
+
+## Everyday keys
+
+| | |
+|---|---|
+| `/switch` or **Ctrl+^** | Move to another agent, conversation included |
+| `/ask codex <msg>` | One question to another agent |
+| `@file` | Attach a file to your message |
+| `/task` | The shared task: plan, who did what, where it stopped, files changed |
+| `/undo` | Revert the last turn's changes |
+| `/usage`, `/budget` | Usage and spend per agent |
+| `/model`, `/effort`, **Shift+Tab** | Pick the model or reasoning effort, cycle permission mode |
+| **Ctrl+O** | Expand cut-off tool output and thinking |
+| Select with the mouse | Copies the text to your clipboard |
+| `/theme dark`, `light`, `auto` | Colour theme (auto follows your terminal) |
+| **Esc** | Stop the current turn |
+| `/` | All commands |
+
+<details>
+<summary><b>Configuration</b></summary>
+
+`~/.codemax/config.json` is created on first run. `codemax config` prints it.
+
+| Key | Default | What it does |
+|---|---|---|
+| `order` | `["claude", "codex", "opencode", "cursor", "grok", "gemini", "copilot"]` | Which agent comes next on a handoff |
+| `budgets` | `{}` | Daily limit per agent, e.g. `{"claude": 20, "all": 50}` |
+| `routes` | `[]` | Send matching messages to a specific agent |
+| `checkpoints` | `true` | Snapshots for `/undo` |
+| `autoSwitch` | `true` | Offer a handoff when an agent runs out |
+| `summarizeOnSwitch` | `true` | Ask the outgoing agent for a summary before a switch. Only used for history recorded before the step journal; otherwise the next agent resumes from the recorded steps |
+| `priceUpdates` | `true` | Weekly price list refresh |
+| `hotkeys` | `["ctrl+/", "ctrl+^"]` | Keys that open the agent switcher |
+
+</details>
+
+<details>
+<summary><b>CLI commands</b></summary>
+
+```
+codemax [--agent <id>] [--fresh]   start chatting
+codemax doctor [--fix]             check nothing bills an API key
+codemax agents                     installed agents and their quota
+codemax usage [--all]              usage for this project or all projects
+codemax prices [update]            price list used for usage values
+codemax history | brief | status | config | keys
+```
+
+</details>
+
+<details>
+<summary><b>Privacy and billing</b></summary>
+
+- Your code goes only to the agents you already use, under your own logins.
+- codemax always removes vendor API keys from the agents it starts, and `codemax doctor --fix` removes any left in Claude Code's settings.
+- Grok follows your Claude Code permission setting. If that is `auto`, Grok acts without asking, and codemax warns you.
+- Its only network call is a weekly price-list download, which `priceUpdates: false` turns off.
+- Usage values are what your plans covered at public API rates, not money you spent.
+
+</details>
+
+## Contributing
+
+Issues and pull requests are welcome. First-time contributors sign a short [CLA](CLA.md) on their pull request. See [CONTRIBUTING.md](CONTRIBUTING.md) and [PLAN.md](PLAN.md) for design notes.
+
+```sh
+bun test && bun run typecheck
+```
+
+Not affiliated with Anthropic, OpenAI, xAI, Google or the OpenCode team.
+
+## License
+
+Copyright © 2026 [Saidev Dhal](https://saidev.codes). Free and open source under the [GNU AGPL-3.0](LICENSE), with an [added permission](NOTICE) for the agent tools codemax drives.
+
+You can use, change and share codemax. If you distribute a modified version, or run one as a service, you must publish your changes under the same license. The codemax name and logo are not covered by the license: forks need their own name. See [TRADEMARKS.md](TRADEMARKS.md).

package/TRADEMARKS.md

@@ -0,0 +1,27 @@
+# codemax trademark policy
+
+The codemax code is open source under the [AGPL-3.0](LICENSE). The **codemax name, the halftone wordmark and the "cm" icon** are not covered by that license. They identify the official project, and this policy says how you can use them.
+
+## You can, without asking
+
+- Say your project is **based on codemax** or **a fork of codemax**, or that it **works with codemax**.
+- Use the name to talk about codemax accurately: in articles, talks, tutorials, comparisons and reviews.
+- Keep the name in the code, file names and git history of an unmodified copy.
+- Link to the official project with the name: https://github.com/SkidGod4444/codemax-cli or https://codemax.saidev.codes.
+
+## You can't, without written permission
+
+- Name a fork, product, package, command, domain or company **codemax**, or something confusingly close (for example "codemax pro", "codemaxx", "code-max").
+- Use the codemax wordmark or icon for your own project, or a logo that looks like them.
+- Suggest that your project is official, endorsed by or affiliated with codemax or Saidev Dhal.
+- Publish a modified build under the codemax name on a package registry, app store or download page.
+
+## If you fork
+
+Give your fork its own name and logo before you publish it. Keep the copyright and license notices in `LICENSE` and `NOTICE`, as the AGPL requires. A line such as "based on codemax" is welcome.
+
+## Questions
+
+Ask before you're unsure: open an issue on the repository, or contact Saidev Dhal at https://saidev.codes.
+
+This policy may be updated as the project grows.

package/bin/codemax

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+import "../src/cli.ts";

package/bin/codemax.cjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+// codemax launcher for npm installs (`npm i -g codemax-cli`, `npx codemax-cli`).
+// codemax runs on Bun; this finds a Bun binary and starts src/cli.ts with it:
+//   1. the `bun` npm package installed alongside codemax (a dependency),
+//   2. its platform package directly (when install scripts were skipped),
+//   3. a `bun` already on PATH.
+"use strict";
+const { spawn, spawnSync } = require("node:child_process");
+const { existsSync } = require("node:fs");
+const { dirname, join } = require("node:path");
+
+const cli = join(__dirname, "..", "src", "cli.ts");
+const exe = process.platform === "win32" ? "bun.exe" : "bun";
+
+function works(path) {
+  if (!path || !existsSync(path)) return false;
+  const r = spawnSync(path, ["--version"], { stdio: "ignore", timeout: 10000 });
+  return r.status === 0;
+}
+
+function resolveIn(pkg, ...rest) {
+  try {
+    return join(dirname(require.resolve(`${pkg}/package.json`)), ...rest);
+  } catch {
+    return null;
+  }
+}
+
+function isMusl() {
+  if (process.platform !== "linux") return false;
+  try {
+    const report = process.report && process.report.getReport();
+    return !(report && report.header && report.header.glibcVersionRuntime);
+  } catch {
+    return false;
+  }
+}
+
+function platformPackage() {
+  const arch = process.arch === "arm64" ? "aarch64" : process.arch === "x64" ? "x64" : null;
+  if (!arch) return null;
+  if (process.platform === "darwin") return `@oven/bun-darwin-${arch}`;
+  if (process.platform === "win32") return `@oven/bun-windows-${arch}`;
+  if (process.platform === "linux") return `@oven/bun-linux-${arch}${isMusl() ? "-musl" : ""}`;
+  return null;
+}
+
+function findBun() {
+  const fromPackage = resolveIn("bun", "bin", "bun.exe");
+  if (works(fromPackage)) return fromPackage;
+  const pp = platformPackage();
+  const fromPlatform = pp && resolveIn(pp, "bin", exe);
+  if (works(fromPlatform)) return fromPlatform;
+  const which = spawnSync(process.platform === "win32" ? "where" : "which", ["bun"], { encoding: "utf8" });
+  const onPath = which.status === 0 ? which.stdout.split(/\r?\n/)[0].trim() : null;
+  if (works(onPath)) return onPath;
+  return null;
+}
+
+const bun = findBun();
+if (!bun) {
+  console.error("codemax: could not find Bun, which codemax runs on.");
+  console.error("Reinstall with `npm i -g codemax-cli` (it installs Bun), or install Bun from https://bun.sh");
+  process.exit(1);
+}
+
+const child = spawn(bun, [cli, ...process.argv.slice(2)], { stdio: "inherit" });
+for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+  process.on(sig, () => {
+    // The TUI handles Ctrl+C itself; forward only what the child would not see.
+    if (sig !== "SIGINT") child.kill(sig);
+  });
+}
+child.on("exit", (code, signal) => {
+  if (signal) process.kill(process.pid, signal);
+  else process.exit(code ?? 0);
+});

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "codemax-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "One terminal for every coding agent you pay for: drive Claude Code, Codex, OpenCode, Grok and Gemini CLI from one chat, on your subscriptions, with context that survives switching agents.",
+  "keywords": [
+    "acp",
+    "agent-client-protocol",
+    "ai",
+    "claude-code",
+    "cli",
+    "codex",
+    "coding-agent",
+    "gemini-cli",
+    "grok",
+    "opencode",
+    "terminal",
+    "tui"
+  ],
+  "homepage": "https://github.com/SkidGod4444/codemax-cli#readme",
+  "bugs": {
+    "url": "https://github.com/SkidGod4444/codemax-cli/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SkidGod4444/codemax-cli.git"
+  },
+  "license": "AGPL-3.0-only",
+  "author": "Saidev Dhal",
+  "type": "module",
+  "bin": {
+    "codemax": "bin/codemax.cjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE",
+    "TRADEMARKS.md"
+  ],
+  "engines": {
+    "node": ">=18",
+    "bun": ">=1.3.0"
+  },
+  "scripts": {
+    "dev": "bun src/cli.ts",
+    "typecheck": "bun x tsc --noEmit",
+    "test": "bun test",
+    "build": "bun build --compile --minify src/cli.ts --outfile dist/codemax && (test \"$(uname)\" != Darwin || codesign --force --sign - dist/codemax)",
+    "prepublishOnly": "bun run typecheck && bun test"
+  },
+  "dependencies": {
+    "@agentclientprotocol/sdk": "1.9.0",
+    "@opentui/core": "0.6.6",
+    "@zed-industries/claude-code-acp": "0.16.2",
+    "bun": "^1.3.5"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.6.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/adapters/claude.ts

@@ -0,0 +1,43 @@
+import { join } from "node:path";
+import { existsSync } from "node:fs";
+import type { Adapter, LaunchOptions, LaunchSpec, SessionRef } from "./types.ts";
+import { HOME, escapeCwd } from "../core/paths.ts";
+import { detectBin } from "./detect.ts";
+import { parseClaudeTranscript } from "../transcripts/claude.ts";
+
+function transcriptPath(cwd: string, id: string) {
+  return join(HOME, ".claude", "projects", escapeCwd(cwd), `${id}.jsonl`);
+}
+
+export const claude: Adapter = {
+  id: "claude",
+  name: "Claude Code",
+  bin: "claude",
+  detect: () => detectBin("claude", ["--version"]),
+  newSessionId: () => crypto.randomUUID(),
+  launch(o: LaunchOptions): LaunchSpec {
+    // Settings files can inject ANTHROPIC_API_KEY via their "env" block; blank it so the
+    // claude.ai login is billed. (The ACP engine path cannot pass this and is gated by doctor.)
+    const cmd = ["claude", "--settings", JSON.stringify({ env: { ANTHROPIC_API_KEY: "", ANTHROPIC_AUTH_TOKEN: "" } })];
+    if (o.resume) cmd.push("--resume", o.resume.id);
+    else if (o.sessionId) cmd.push("--session-id", o.sessionId);
+    if (o.extraArgs) cmd.push(...o.extraArgs);
+    // Interactive claude accepts an initial prompt as the positional argument.
+    if (o.prompt) cmd.push(o.prompt);
+    return { cmd, promptConsumed: !!o.prompt };
+  },
+  async locateSession({ cwd, startedAt, sessionId }) {
+    if (!sessionId) return null;
+    // The transcript appears after the first message; until then the session
+    // does not exist on Claude's side and could not be resumed.
+    const p = transcriptPath(cwd, sessionId);
+    if (!existsSync(p)) return null;
+    return { agent: "claude", id: sessionId, transcriptPath: p, cwd, startedAt, lastUsedAt: Date.now() };
+  },
+  async readTranscript(ref: SessionRef) {
+    const p = ref.transcriptPath ?? transcriptPath(ref.cwd, ref.id);
+    return parseClaudeTranscript(p, ref.id);
+  },
+  quotaPatterns: [/claude (ai )?usage limit reached/i, /out of extra usage/i, /limit will reset at/i],
+  apiKeyEnv: ["ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN"],
+};

package/src/adapters/codex.ts

@@ -0,0 +1,101 @@
+import { join } from "node:path";
+import { existsSync, readdirSync, statSync, openSync, readSync, closeSync } from "node:fs";
+import type { Adapter, LaunchOptions, LaunchSpec, SessionRef } from "./types.ts";
+import { HOME } from "../core/paths.ts";
+import { detectBin } from "./detect.ts";
+import { parseCodexTranscript, codexQuotaFromRollout } from "../transcripts/codex.ts";
+
+const SESSIONS = join(HOME, ".codex", "sessions");
+
+/** First line of a file. session_meta lines run to tens of KB, so read in chunks until a newline. */
+function firstLine(path: string, max = 4 * 1024 * 1024): string {
+  const fd = openSync(path, "r");
+  try {
+    const chunks: Buffer[] = [];
+    let total = 0;
+    while (total < max) {
+      const buf = Buffer.alloc(65536);
+      const n = readSync(fd, buf, 0, buf.length, total);
+      if (n <= 0) break;
+      chunks.push(buf.subarray(0, n));
+      total += n;
+      if (buf.subarray(0, n).includes(0x0a)) break;
+    }
+    return Buffer.concat(chunks).toString("utf8").split("\n")[0] ?? "";
+  } finally {
+    closeSync(fd);
+  }
+}
+
+/** Rollout files written on/after `since`, newest first. Scans today and yesterday. */
+function recentRollouts(since: number): string[] {
+  const out: string[] = [];
+  for (const dayOffset of [0, 1]) {
+    const d = new Date(since - dayOffset * 86_400_000);
+    const dir = join(SESSIONS, String(d.getFullYear()), String(d.getMonth() + 1).padStart(2, "0"), String(d.getDate()).padStart(2, "0"));
+    if (!existsSync(dir)) continue;
+    for (const f of readdirSync(dir)) {
+      if (!f.endsWith(".jsonl")) continue;
+      const p = join(dir, f);
+      if (statSync(p).mtimeMs >= since - 2000) out.push(p);
+    }
+  }
+  return out.sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs);
+}
+
+function findRolloutById(id: string): string | undefined {
+  // Walk year/month/day dirs, newest first.
+  if (!existsSync(SESSIONS)) return undefined;
+  const years = readdirSync(SESSIONS).sort().reverse();
+  for (const y of years) {
+    const yd = join(SESSIONS, y);
+    for (const m of readdirSync(yd).sort().reverse()) {
+      const md = join(yd, m);
+      for (const d of readdirSync(md).sort().reverse()) {
+        const dd = join(md, d);
+        const hit = readdirSync(dd).find((f) => f.includes(id));
+        if (hit) return join(dd, hit);
+      }
+    }
+  }
+  return undefined;
+}
+
+export const codex: Adapter = {
+  id: "codex",
+  name: "Codex",
+  bin: "codex",
+  detect: () => detectBin("codex", ["--version"]),
+  launch(o: LaunchOptions): LaunchSpec {
+    // Global flags go before the subcommand so `resume` accepts them too.
+    const cmd = ["codex", "-C", o.cwd];
+    if (o.resume) cmd.push("resume", o.resume.id);
+    if (o.extraArgs) cmd.push(...o.extraArgs);
+    if (o.prompt) cmd.push(o.prompt);
+    return { cmd, promptConsumed: !!o.prompt };
+  },
+  async locateSession({ cwd, startedAt }) {
+    for (const p of recentRollouts(startedAt)) {
+      try {
+        const meta = JSON.parse(firstLine(p));
+        if (meta.type === "session_meta" && meta.payload?.cwd === cwd) {
+          return { agent: "codex", id: meta.payload.id ?? meta.payload.session_id, transcriptPath: p, cwd, startedAt, lastUsedAt: Date.now() };
+        }
+      } catch {
+        /* partial write, try next */
+      }
+    }
+    return null;
+  },
+  async readTranscript(ref: SessionRef) {
+    const p = ref.transcriptPath ?? findRolloutById(ref.id);
+    return p ? parseCodexTranscript(p, ref.id) : [];
+  },
+  async probeQuota(ref) {
+    const p = ref?.transcriptPath ?? (ref ? findRolloutById(ref.id) : undefined);
+    if (!p) return null;
+    return codexQuotaFromRollout(p);
+  },
+  quotaPatterns: [/you['’]ve hit your usage limit/i, /usage limit reached/i],
+  apiKeyEnv: ["OPENAI_API_KEY"],
+};

package/src/adapters/detect.ts

@@ -0,0 +1,16 @@
+import type { DetectResult } from "./types.ts";
+import { platformArgv } from "../core/spawn.ts";
+
+export async function detectBin(bin: string, versionArgs: string[] = ["--version"]): Promise<DetectResult> {
+  const path = Bun.which(bin);
+  if (!path) return { installed: false };
+  try {
+    const p = Bun.spawn(platformArgv([path, ...versionArgs]), { stdout: "pipe", stderr: "pipe" });
+    const text = (await new Response(p.stdout).text()).trim();
+    await p.exited;
+    const m = text.match(/\d+\.\d+(\.\d+)?/);
+    return { installed: true, path, version: m?.[0] ?? text.split("\n")[0] };
+  } catch {
+    return { installed: true, path };
+  }
+}

package/src/adapters/index.ts

@@ -0,0 +1,21 @@
+import type { Adapter, AgentId } from "./types.ts";
+import { claude } from "./claude.ts";
+import { codex } from "./codex.ts";
+import { opencode, cursor, grok, gemini, copilot, fake } from "./simple.ts";
+
+const all: Adapter[] = [claude, codex, opencode, cursor, grok, gemini, copilot];
+if (process.env.CODEMAX_FAKE_AGENT) all.push(fake);
+
+export const adapters: Record<string, Adapter> = Object.fromEntries(all.map((a) => [a.id, a]));
+
+export function getAdapter(id: string): Adapter {
+  const a = adapters[id];
+  if (!a) throw new Error(`unknown agent "${id}". Known: ${Object.keys(adapters).join(", ")}`);
+  return a;
+}
+
+export function listAdapters(order: AgentId[]): Adapter[] {
+  const ranked = order.map((id) => adapters[id]).filter((a): a is Adapter => !!a);
+  const rest = all.filter((a) => !ranked.includes(a));
+  return [...ranked, ...rest];
+}

package/src/adapters/simple.ts

@@ -0,0 +1,89 @@
+import type { Adapter, AgentId, LaunchOptions, LaunchSpec } from "./types.ts";
+import { detectBin } from "./detect.ts";
+
+/**
+ * Adapters for agents whose transcripts we do not parse yet (v0.2 work).
+ * They launch, pass through, and get the handoff brief typed into the TUI.
+ */
+function simple(opts: {
+  id: AgentId;
+  name: string;
+  bin: string;
+  versionArgs?: string[];
+  resumeArgs?: (id: string) => string[];
+  promptPositional?: boolean;
+  patterns?: RegExp[];
+  apiKeyEnv?: string[];
+}): Adapter {
+  return {
+    id: opts.id,
+    name: opts.name,
+    bin: opts.bin,
+    detect: () => detectBin(opts.bin, opts.versionArgs),
+    launch(o: LaunchOptions): LaunchSpec {
+      const cmd = [opts.bin];
+      if (o.resume && opts.resumeArgs) cmd.push(...opts.resumeArgs(o.resume.id));
+      if (o.extraArgs) cmd.push(...o.extraArgs);
+      const consumed = !!o.prompt && !!opts.promptPositional;
+      if (consumed) cmd.push(o.prompt!);
+      return { cmd, promptConsumed: consumed };
+    },
+    async locateSession() {
+      return null;
+    },
+    quotaPatterns: opts.patterns ?? [],
+    apiKeyEnv: opts.apiKeyEnv ?? [],
+  };
+}
+
+export const opencode = simple({
+  id: "opencode",
+  name: "OpenCode",
+  bin: "opencode",
+  // TUI positional is a project path, not a prompt → brief is typed in.
+  patterns: [/usage limit reached/i],
+});
+
+export const cursor = simple({
+  id: "cursor",
+  name: "Cursor Agent",
+  bin: "cursor-agent",
+  resumeArgs: (id) => ["--resume", id],
+  promptPositional: true,
+  patterns: [/usage limit reached/i, /out of (fast )?requests/i],
+  apiKeyEnv: ["CURSOR_API_KEY"],
+});
+
+export const grok = simple({
+  id: "grok",
+  name: "Grok CLI",
+  bin: "grok",
+  resumeArgs: (id) => ["--resume", id],
+  patterns: [/usage limit reached/i],
+  apiKeyEnv: ["XAI_API_KEY", "GROK_API_KEY"],
+});
+
+export const gemini = simple({
+  id: "gemini",
+  name: "Gemini CLI",
+  bin: "gemini",
+  promptPositional: false,
+  patterns: [/quota exceeded/i, /RESOURCE_EXHAUSTED/],
+  apiKeyEnv: ["GEMINI_API_KEY", "GOOGLE_API_KEY"],
+});
+
+export const copilot = simple({
+  id: "copilot",
+  name: "Copilot CLI",
+  bin: "copilot",
+  patterns: [/premium requests? (limit|exhausted|used up)/i],
+});
+
+/** Test-only agent: a plain shell, enabled with CODEMAX_FAKE_AGENT=1. */
+export const fake = simple({
+  id: "fake",
+  name: "Fake (sh)",
+  bin: "sh",
+  versionArgs: ["-c", "echo 0.0.0"],
+  patterns: [/FAKE_QUOTA_HIT/],
+});