@warlock.js/ai-cli 0.0.0-stage → 5.31.0

package/llms-full.txt

@@ -0,0 +1,373 @@
+# Warlock AI Cli — full skills
+
+> Package: `@warlock.js/ai-cli`
+
+> Generated artifact. Concatenates every SKILL.md and reference file under `@warlock.js/ai-cli/skills/`. Re-run `node scripts/generate-llms.mjs` after any change.
+
+## run-cli-agents  `@warlock.js/ai-cli/run-cli-agents/SKILL.md`
+
+---
+name: run-cli-agents
+description: 'Run vendor coding CLIs headless as agents with @warlock.js/ai-cli. Triggers: `ai.cli`, `cli.claudeCode`, `cli.codex`, `cli.antigravity`, `cli.qwenCode`, `cli.kimi`, `cli.cursor`, `cli.copilot`, `cli.grok`, `cli.opencode`, `cli.amp`, `cli.droid`, `cli.mistralVibe`, `cli.aider`, `cli.reasonix`, `createCliAgent`, `CliSession`, `session.events`, `session.done`, `CliEvent`, `CliResult`, `sessionRef`, `resume`, `permission: "bypass"`, `CliMcpServers`, `home: "private"`, `inheritEnv`, `CliError`, `agent.model`, `cliModel`; ''run claude code from node'', ''orchestrate codex / copilot / cursor as workers'', ''stream a CLI agent''s tool calls'', ''resume a CLI session'', ''cancel a coding CLI and its child processes'', ''read token usage from a CLI run'', ''give a CLI MCP servers without putting tokens in argv'', ''use a CLI as an ai.agent model''; typical import `import { cli } from "@warlock.js/ai-cli"`. Skip: writing an adapter for another CLI — the `write-a-cli-adapter` topic; direct provider calls — the `run-ai-agent` topic of the `warlock-js-ai` skill.'
+---
+
+# Run coding CLIs as agents
+
+`@warlock.js/ai-cli` drives vendor coding CLIs headless. One run is one session. The vendor's stream is reduced to one event model, and `done()` resolves the final text, the usage and a session reference you can resume. It ships fourteen adapters: Claude Code, Codex, Antigravity, Qwen Code, Kimi Code, Cursor, Copilot, Grok Build, OpenCode, Amp, Factory Droid, Mistral Vibe, Aider and Reasonix. The CLIs themselves are not installed by the package.
+
+## Run a prompt and read the events
+
+```ts
+import { cli } from "@warlock.js/ai-cli";
+
+const claude = cli.claudeCode({ model: "sonnet", apiKey: process.env.ANTHROPIC_API_KEY });
+const session = await claude.run("Fix the failing test in src/math.spec.ts", {
+  cwd: "/srv/acme-api",
+});
+
+for await (const event of session.events) {
+  switch (event.type) {
+    case "session.started":
+      console.log("session", event.sessionRef);
+      break;
+    case "message":
+      if (event.delta) process.stdout.write(event.text);
+      break;
+    case "tool.call":
+      console.log("\ntool", event.name, event.input);
+      break;
+    case "tool.result":
+      console.log(event.isError ? "failed:" : "ok:", event.output.slice(0, 200));
+      break;
+    case "usage":
+      console.log("tokens", event.usage.total);
+      break;
+    case "error":
+      console.error(event.fatal ? "fatal:" : "warning:", event.message);
+      break;
+    case "session.ended":
+      console.log("ended", event.status, event.exitCode);
+      break;
+  }
+}
+
+const result = await session.done();
+
+if (result.status === "completed") {
+  console.log(result.text, result.usage, result.sessionRef);
+} else {
+  console.error(result.status, result.error, result.stderr);
+}
+```
+
+- **`session.events`** replays from the first event on every iteration, and ends after `session.ended`.
+- **`done()` never rejects.** Branch on `status`: `completed`, `failed`, `cancelled` or `timeout`.
+- **`text`** is the vendor's final record, or else the last assistant message. `messages` holds every complete message.
+- **`run()` rejects only for setup problems,** with a `CliError` whose `type` is one of:
+  - `not-found` — the executable is not on `PATH`;
+  - `capability` — `--help` lacks a needed flag; the error carries `flag` and `version`;
+  - `probe-failed` — the CLI's help could not be read;
+  - `unsupported-option` — the adapter cannot honour an option;
+  - `prompt-transport` — the prompt fits neither argv nor stdin.
+
+`ai.cli` is the same namespace once `import "@warlock.js/ai-cli"` has run.
+
+## Resume, cancel, time out
+
+```ts
+import { cli } from "@warlock.js/ai-cli";
+
+const codex = cli.codex({ cwd: "/srv/acme-api" });
+const plan = await (await codex.run("Plan the billing refactor; do not edit files")).done();
+
+const controller = new AbortController();
+const step = await codex.run("Implement step 1 of the plan", {
+  resume: plan.sessionRef,
+  signal: controller.signal,
+  timeoutMs: 15 * 60_000,
+});
+
+setTimeout(() => controller.abort(), 60_000); // or step.cancel()
+
+const outcome = await step.done();
+
+console.log(outcome.status); // "cancelled" after the abort
+```
+
+Abort and timeout kill the whole process tree. On POSIX that is the CLI's process group (SIGTERM, then SIGKILL after `killGraceMs`, default 2000); on Windows it is `taskkill /T /F` on its PID. A run whose signal is already aborted never spawns.
+
+## Permissions — bypass is opt-in
+
+```ts
+import { cli } from "@warlock.js/ai-cli";
+
+// Default "standard": the CLI's own non-interactive rules; anything needing approval is refused.
+const reviewer = cli.copilot({ cwd: "/srv/acme-api" });
+
+// "bypass": every tool call approved without asking. Only for a sandboxed run.
+const fixer = cli.grok({ cwd: "/sandbox/acme-api", permission: "bypass" });
+
+const review = await (await reviewer.run("Review src/billing for bugs")).done();
+const fix = await (
+  await fixer.run("Apply the fixes from the review", { permission: "bypass" })
+).done();
+
+console.log(review.text, fix.status);
+```
+
+What `"standard"` allows depends on the vendor:
+
+- **Read-only:** Codex and Droid. Allow edits with `args: ["-c", "sandbox_mode=workspace-write"]` (Codex) or `args: ["--auto", "medium"]` (Droid).
+- **Permissive:** OpenCode and Amp.
+- **Refused:** Kimi Code always approves in print mode, so its adapter rejects `"standard"` and needs `"bypass"`.
+
+## MCP servers, secrets and homes
+
+```ts
+import { cli } from "@warlock.js/ai-cli";
+
+const claude = cli.claudeCode({
+  apiKey: process.env.ANTHROPIC_API_KEY, // exported as ANTHROPIC_API_KEY, never argv
+  inheritEnv: ["GITHUB_TOKEN"], // minimal system env + these names only
+});
+
+const session = await claude.run("Triage the open issues", {
+  mcp: {
+    tracker: {
+      type: "stdio",
+      command: "npx",
+      args: ["-y", "@acme/tracker-mcp"],
+      env: { TRACKER_TOKEN: process.env.TRACKER_TOKEN ?? "" },
+    },
+    docs: {
+      type: "http",
+      url: "https://mcp.acme.dev/mcp",
+      headers: { Authorization: `Bearer ${process.env.DOCS_TOKEN ?? ""}` },
+    },
+  },
+});
+
+console.log((await session.done()).text);
+```
+
+**MCP servers.** They are written as a mode-0600 file inside a private per-run directory (mode 0700), never into argv, and the file is removed after the run. CLIs that read MCP only from their config home (Kimi, Grok, Cursor, Droid, Antigravity, Mistral Vibe, Reasonix) need the default private home. Aider has no MCP support.
+
+**Homes.** The `home` option takes one of:
+
+- `"private"` (default) — a fresh config home per run;
+- an absolute path — a home you own, for example one you logged in to;
+- `"inherit"` — your normal config.
+
+The adapter's home variable (`CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `COPILOT_HOME`, `GROK_HOME`, …) is pointed at it.
+
+## Use a CLI as an `ai.agent` model
+
+```ts
+import { ai, budget } from "@warlock.js/ai";
+import { cli } from "@warlock.js/ai-cli";
+
+const coder = cli.codex({ cwd: "/srv/acme-api" });
+
+const reviewer = ai.agent({
+  model: coder.model({ name: "codex-reviewer" }),
+  middleware: [budget({ maxTokens: 200_000 })],
+});
+
+const review = await reviewer.execute("Review the last commit for bugs.");
+
+console.log(review.text, review.usage.total);
+```
+
+How the model behaves:
+
+- **One fresh CLI session per call.** System messages lead the prompt, and a history is rendered as a transcript.
+- **The CLI uses its own tools.** A call with agent `tools` is refused; give the CLI `mcp` servers instead.
+- **Streaming yields the final answer once the session ends.**
+- **A failed run throws `CliError` with `type: "run-failed"`,** so `fallbackModel` works.
+- **Pass `pricing`** for USD cost.
+
+## Pitfalls
+
+- Install and log in to the vendor CLI yourself. With the default private home, authenticate with `apiKey`/`env`.
+- `effort` is refused by CLIs without an effort control (Qwen Code, Kimi, Cursor, Mistral Vibe), and `model` is refused by Amp. Nothing is silently ignored.
+- `args` is passed verbatim; never put a token there.
+- The vendor table in the docs ("Vendor adapters") lists each CLI's flags, stream format, and the version it was verified against.
+
+
+## write-a-cli-adapter  `@warlock.js/ai-cli/write-a-cli-adapter/SKILL.md`
+
+---
+name: write-a-cli-adapter
+description: 'Write a CliAdapter for a coding CLI that @warlock.js/ai-cli does not ship. Triggers: `CliAdapter`, `CliLaunchContext`, `CliLaunchPlan`, `CliStreamParser`, `cli.custom`, `createCliAgent`, `jsonLinesParser`, `stringField`, `numberField`, `usageOf`, `mcpServersJson`, `jsonFile`, `toToml`, `mapEffort`, `argvPrompt`, `promptFile`, `requirePrivateHome`, `unsupportedOption`, `createClaudeStreamParser`, `helpLists`, `missingFlags`, `requires`, `verification`; ''add a new coding CLI'', ''support another agent CLI'', ''parse a vendor JSONL stream'', ''adapter for a new CLI version''; typical import `import { cli, jsonLinesParser, type CliAdapter } from "@warlock.js/ai-cli"`. Skip: using the built-in adapters — the `run-cli-agents` topic.'
+---
+
+# Write a CLI adapter
+
+An adapter is a plain object with two jobs: `plan(context)` builds argv, stdin, environment and files for one run, and `parser(context)` turns stdout lines into the unified events. The runner does the rest: executable lookup, the Windows `.cmd` rules, the capability probe, homes, secrets, cancellation and the result.
+
+```ts
+import path from "node:path";
+import {
+  cli,
+  jsonFile,
+  jsonLinesParser,
+  mcpServersJson,
+  numberField,
+  stringField,
+  usageOf,
+  type CliAdapter,
+  type CliLaunchFile,
+} from "@warlock.js/ai-cli";
+
+export const acmeAdapter: CliAdapter = {
+  name: "acme",
+  title: "Acme Agent",
+  command: "acme",
+  apiKeyEnv: ["ACME_API_KEY"],
+  homeEnv: ["ACME_HOME"],
+  transports: ["argv", "stdin"],
+  effort: false,
+  mcp: true,
+  probe: { help: [["run", "--help"]], version: ["--version"] },
+  verification: {
+    version: "3.2.0",
+    verifiedBy: "help",
+    sources: ["https://acme.dev/docs/cli"],
+    checkedAt: "2026-10-17",
+  },
+  plan(context) {
+    const args = ["run", "--json"];
+    const requires = ["--json"];
+    const files: CliLaunchFile[] = [];
+
+    if (context.model !== undefined) {
+      args.push("--model", context.model);
+      requires.push("--model");
+    }
+
+    if (context.resume !== undefined) {
+      args.push("--resume", context.resume);
+      requires.push("--resume");
+    }
+
+    if (context.permission === "bypass") {
+      args.push("--yes-to-all");
+      requires.push("--yes-to-all");
+    }
+
+    if (context.mcp !== undefined) {
+      const file = path.join(context.runDir, "mcp.json");
+
+      files.push({ path: file, content: jsonFile({ mcpServers: mcpServersJson(context.mcp) }) });
+      args.push("--mcp-config", file);
+      requires.push("--mcp-config");
+    }
+
+    return {
+      args,
+      tail: context.transport === "argv" ? [context.prompt] : [],
+      stdin: context.transport === "stdin" ? context.prompt : undefined,
+      env: context.home !== undefined ? { ACME_HOME: context.home } : undefined,
+      files,
+      requires,
+    };
+  },
+  parser: () =>
+    jsonLinesParser((record) => {
+      switch (record.type) {
+        case "start":
+          return [{ type: "session.started", sessionRef: stringField(record, "id") }];
+        case "text":
+          return [{ type: "message", text: stringField(record, "text") ?? "", delta: true }];
+        case "tool":
+          return [
+            {
+              type: "tool.call",
+              id: String(record.id),
+              name: String(record.name),
+              input: record.input,
+            },
+          ];
+        case "tool_done":
+          return [
+            {
+              type: "tool.result",
+              id: String(record.id),
+              output: String(record.output),
+              isError: record.ok !== true,
+            },
+          ];
+        case "usage":
+          return [
+            {
+              type: "usage",
+              cumulative: true,
+              usage: usageOf({
+                input: numberField(record, "in"),
+                output: numberField(record, "out"),
+              }),
+            },
+          ];
+        case "error":
+          return [{ type: "error", message: String(record.message), fatal: true }];
+        default:
+          return [];
+      }
+    }),
+};
+
+const acme = cli.custom(acmeAdapter);
+const result = await (await acme.run("Add a health check endpoint", { cwd: "/srv/api" })).done();
+
+console.log(result.status, result.text);
+```
+
+## Rules
+
+- **`requires`:** list every flag and subcommand the plan uses, spelled as `--help` prints it. The probe then fails the run up front, naming the flag and the installed version, if a release drops or renames one. Leave out only a flag the CLI accepts but no longer documents, and say so in a comment.
+- **Secrets:** never put one in `args` or `tail`. Use `env`, or a file under `context.runDir` (written 0600, removed after the run). A home-level config file may be written only when `context.homeIsPrivate`; `requirePrivateHome(context, adapter, "MCP servers")` fails closed otherwise.
+- **Prompt placement:** `tail` goes after the caller's `args`. Wrap a positional prompt in `argvPrompt(prompt)`, so a prompt starting with `-` is not read as a flag. For a `"file"` transport, `promptFile(context)` writes the prompt into the run directory.
+- **Effort:** `mapEffort(effort, { low: "low", high: "high" })` follows the framework clamping rule. Set `effort: true` only when you map it. The runner refuses `effort` for adapters that do not.
+- **Unsupported options:** `throw unsupportedOption(adapter, "why")` for an option the CLI cannot honour; never drop it silently.
+- **Failures:** report a vendor failure as `{ type: "error", fatal: true }`, so a CLI that exits 0 still ends `failed`.
+- **Late session ids:** if the id arrives only at the end, return it from the parser's `sessionRef()`. If the CLI writes its result to a file, point it at `context.runDir` and read the file in the parser's `end()`.
+- **Claude-style streams:** for a CLI that reproduces Claude Code's `stream-json`, reuse `createClaudeStreamParser({ usage: "anthropic" | "inclusive" })`.
+- **Verification:** record `verification` — the version, the sources, and `"help"` or `"docs"`.
+
+## Test without the real CLI
+
+```ts
+// acme-adapter.spec.ts — `acmeAdapter` from above; `readFileSync` from "node:fs",
+// `missingFlags` from "@warlock.js/ai-cli", `expect`/`it` from "vitest".
+it("normalizes a recorded stream and needs only listed flags", () => {
+  const parser = acmeAdapter.parser({
+    prompt: "x",
+    transport: "argv",
+    cwd: "/work",
+    permission: "standard",
+    homeIsPrivate: true,
+    runDir: "/tmp/run",
+    platform: "linux",
+  });
+  const events = readFileSync("fixtures/acme/stream.jsonl", "utf8")
+    .split("\n")
+    .flatMap((line) => parser.line(line));
+
+  expect(events[0]).toMatchObject({ type: "session.started" });
+
+  const plan = acmeAdapter.plan({
+    prompt: "x",
+    transport: "argv",
+    cwd: "/work",
+    model: "fast",
+    permission: "bypass",
+    homeIsPrivate: true,
+    runDir: "/tmp/run",
+    platform: "linux",
+  });
+
+  expect(missingFlags(readFileSync("fixtures/acme/help.txt", "utf8"), plan.requires)).toEqual([]);
+});
+```
+
+

package/llms.txt

@@ -0,0 +1,10 @@
+# Warlock AI Cli
+
+> Package: `@warlock.js/ai-cli`
+
+> Drive vendor coding-agent CLIs (Claude Code, Codex, Copilot, Cursor, …) as first-class @warlock.js/ai agents
+
+## Skills
+
+- [run-cli-agents](@warlock.js/ai-cli/run-cli-agents/SKILL.md): Run vendor coding CLIs headless as agents with @warlock.js/ai-cli. Triggers: `ai.cli`, `cli.claudeCode`, `cli.codex`, `cli.antigravity`, `cli.qwenCode`, `cli.kimi`, `cli.cursor`, `cli.copilot`, `cli.grok`, `cli.opencode`, `cli.amp`, `cli.droid`, `cli.mistralVibe`, `cli.aider`, `cli.reasonix`, `createCliAgent`, `CliSession`, `session.events`, `session.done`, `CliEvent`, `CliResult`, `sessionRef`, `resume`, `permission: "bypass"`, `CliMcpServers`, `home: "private"`, `inheritEnv`, `CliError`, `agent.model`, `cliModel`; 'run claude code from node', 'orchestrate codex / copilot / cursor as workers', 'stream a CLI agent's tool calls', 'resume a CLI session', 'cancel a coding CLI and its child processes', 'read token usage from a CLI run', 'give a CLI MCP servers without putting tokens in argv', 'use a CLI as an ai.agent model'; typical import `import { cli } from "@warlock.js/ai-cli"`. Skip: writing an adapter for another CLI — the `write-a-cli-adapter` topic; direct provider calls — the `run-ai-agent` topic of the `warlock-js-ai` skill.
+- [write-a-cli-adapter](@warlock.js/ai-cli/write-a-cli-adapter/SKILL.md): Write a CliAdapter for a coding CLI that @warlock.js/ai-cli does not ship. Triggers: `CliAdapter`, `CliLaunchContext`, `CliLaunchPlan`, `CliStreamParser`, `cli.custom`, `createCliAgent`, `jsonLinesParser`, `stringField`, `numberField`, `usageOf`, `mcpServersJson`, `jsonFile`, `toToml`, `mapEffort`, `argvPrompt`, `promptFile`, `requirePrivateHome`, `unsupportedOption`, `createClaudeStreamParser`, `helpLists`, `missingFlags`, `requires`, `verification`; 'add a new coding CLI', 'support another agent CLI', 'parse a vendor JSONL stream', 'adapter for a new CLI version'; typical import `import { cli, jsonLinesParser, type CliAdapter } from "@warlock.js/ai-cli"`. Skip: using the built-in adapters — the `run-cli-agents` topic.

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@warlock.js/ai-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "description": "Drive vendor coding-agent CLIs (Claude Code, Codex, Copilot, Cursor, …) as first-class @warlock.js/ai agents",
+  "keywords": [
+    "warlock",
+    "ai",
+    "agent",
+    "cli",
+    "claude-code",
+    "codex",
+    "copilot",
+    "cursor",
+    "coding-agent"
+  ],
+  "author": "Hasan Zohdy",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/warlockjs/framework.git",
+    "directory": "packages/ai-cli"
+  },
+  "peerDependencies": {
+    "@warlock.js/ai": "5.31.0"
+  },
+  "version": "5.31.0",
+  "main": "./cjs/index.cjs",
+  "module": "./esm/index.mjs",
+  "types": "./esm/index.d.mts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./esm/index.d.mts",
+        "default": "./esm/index.mjs"
+      },
+      "require": {
+        "types": "./esm/index.d.mts",
+        "default": "./cjs/index.cjs"
+      }
+    }
+  }
+}

package/skills/README.md

@@ -0,0 +1,13 @@
+# `@warlock.js/ai-cli` — skills index
+
+Per-task skills. Cross-references name the topic ("the `<topic>` topic"), and for another package add its skill ("the `<topic>` topic of the `warlock-js-<pkg>` skill").
+
+## Skills
+
+### `run-cli-agents`
+
+Drive a vendor coding CLI headless with `cli.<vendor>({...})` / `ai.cli.<vendor>` — `run(prompt, { cwd, resume, signal, model, effort, permission, mcp, env })`, the unified `session.events` (`session.started`, `message`, `tool.call`, `tool.result`, `usage`, `error`, `session.ended`), `session.done()` (`status`, `text`, `usage`, `sessionRef`, `exitCode`), resume, cancellation and timeouts, the opt-in `permission: "bypass"`, per-run MCP servers, config homes, `CliError` types, and `agent.model()` to run a CLI as an `ai.agent` model. Load when orchestrating Claude Code, Codex, Copilot, Cursor, Grok, Kimi, Qwen Code, OpenCode, Amp, Droid, Antigravity, Mistral Vibe, Aider or Reasonix from code.
+
+### `write-a-cli-adapter`
+
+Implement a `CliAdapter` for a coding CLI the package does not ship — the launch plan (`args`, `tail`, `stdin`, `env`, `files`, `requires`), the stream parser (`jsonLinesParser`, `sessionRef()`, reading a result file in `end()`), the verification record, and testing against a recorded stream and `--help`. Load when adding a vendor or adjusting an adapter for a new CLI release.

package/skills/index.md

@@ -0,0 +1,22 @@
+---
+description: "Drive vendor coding-agent CLIs headless as @warlock.js/ai agents — Claude Code, Codex, Antigravity, Qwen Code, Kimi Code, Cursor, Copilot, Grok Build, OpenCode, Amp, Factory Droid, Mistral Vibe, Aider, Reasonix. Exports `cli`, `createCliAgent`, `cliModel`, `CliError`, the per-vendor adapters and the adapter building blocks; registers `ai.cli`. Use for: run a coding CLI from code, stream its tool calls and text as one event model, resume or cancel a CLI session, read its token usage, give a CLI per-run MCP servers without leaking tokens, use a CLI as an ai.agent model, add an adapter for another CLI. Not this package: direct model calls → @warlock.js/ai with a provider adapter; a policy-jailed shell/file workspace → @warlock.js/ai-workspace; MCP clients and servers → @warlock.js/ai-tools."
+---
+
+# @warlock.js/ai-cli
+
+Many teams run the vendors' own agent CLIs on the subscriptions they already pay for. This package launches those CLIs headless, one session per run, and reduces each vendor's JSONL stream to one event model, with resume, process-tree cancellation, usage and per-run MCP servers. Importing the package registers `ai.cli` on the shared `ai` object.
+
+## The 80% path
+
+1. Pick a vendor factory and run a prompt; read `session.events` and `await session.done()` (`run-cli-agents`).
+2. Resume with `done().sessionRef`, cancel with a `signal`, and attach MCP servers with `mcp`.
+3. To give the CLI to `ai.agent` (budgets, guardrails, observers), use `agent.model()`.
+4. For a CLI that is not built in, write an adapter (`write-a-cli-adapter`).
+
+## Conventions and pitfalls
+
+- `permission` defaults to `"standard"` (the CLI's own non-interactive rules); `"bypass"` must be opted into. Kimi Code has no standard mode and requires `"bypass"`.
+- Secrets go in `apiKey`, `env`, or MCP `env`/`headers`, never in `args`.
+- The default home is private per run: authenticate with `apiKey`/`env`, or pass a home you logged in to.
+- `run()` rejects only for setup problems (`CliError`: `not-found`, `capability`, `unsupported-option`, …). `done()` never rejects; check `status`.
+- The installed CLI's `--help` must list every flag the adapter uses, so a CLI release with renamed flags fails closed with the flag and version in the error.

package/skills/run-cli-agents/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: run-cli-agents
+description: 'Run vendor coding CLIs headless as agents with @warlock.js/ai-cli. Triggers: `ai.cli`, `cli.claudeCode`, `cli.codex`, `cli.antigravity`, `cli.qwenCode`, `cli.kimi`, `cli.cursor`, `cli.copilot`, `cli.grok`, `cli.opencode`, `cli.amp`, `cli.droid`, `cli.mistralVibe`, `cli.aider`, `cli.reasonix`, `createCliAgent`, `CliSession`, `session.events`, `session.done`, `CliEvent`, `CliResult`, `sessionRef`, `resume`, `permission: "bypass"`, `CliMcpServers`, `home: "private"`, `inheritEnv`, `CliError`, `agent.model`, `cliModel`; ''run claude code from node'', ''orchestrate codex / copilot / cursor as workers'', ''stream a CLI agent''s tool calls'', ''resume a CLI session'', ''cancel a coding CLI and its child processes'', ''read token usage from a CLI run'', ''give a CLI MCP servers without putting tokens in argv'', ''use a CLI as an ai.agent model''; typical import `import { cli } from "@warlock.js/ai-cli"`. Skip: writing an adapter for another CLI — the `write-a-cli-adapter` topic; direct provider calls — the `run-ai-agent` topic of the `warlock-js-ai` skill.'
+---
+
+# Run coding CLIs as agents
+
+`@warlock.js/ai-cli` drives vendor coding CLIs headless. One run is one session. The vendor's stream is reduced to one event model, and `done()` resolves the final text, the usage and a session reference you can resume. It ships fourteen adapters: Claude Code, Codex, Antigravity, Qwen Code, Kimi Code, Cursor, Copilot, Grok Build, OpenCode, Amp, Factory Droid, Mistral Vibe, Aider and Reasonix. The CLIs themselves are not installed by the package.
+
+## Run a prompt and read the events
+
+```ts
+import { cli } from "@warlock.js/ai-cli";
+
+const claude = cli.claudeCode({ model: "sonnet", apiKey: process.env.ANTHROPIC_API_KEY });
+const session = await claude.run("Fix the failing test in src/math.spec.ts", {
+  cwd: "/srv/acme-api",
+});
+
+for await (const event of session.events) {
+  switch (event.type) {
+    case "session.started":
+      console.log("session", event.sessionRef);
+      break;
+    case "message":
+      if (event.delta) process.stdout.write(event.text);
+      break;
+    case "tool.call":
+      console.log("\ntool", event.name, event.input);
+      break;
+    case "tool.result":
+      console.log(event.isError ? "failed:" : "ok:", event.output.slice(0, 200));
+      break;
+    case "usage":
+      console.log("tokens", event.usage.total);
+      break;
+    case "error":
+      console.error(event.fatal ? "fatal:" : "warning:", event.message);
+      break;
+    case "session.ended":
+      console.log("ended", event.status, event.exitCode);
+      break;
+  }
+}
+
+const result = await session.done();
+
+if (result.status === "completed") {
+  console.log(result.text, result.usage, result.sessionRef);
+} else {
+  console.error(result.status, result.error, result.stderr);
+}
+```
+
+- **`session.events`** replays from the first event on every iteration, and ends after `session.ended`.
+- **`done()` never rejects.** Branch on `status`: `completed`, `failed`, `cancelled` or `timeout`.
+- **`text`** is the vendor's final record, or else the last assistant message. `messages` holds every complete message.
+- **`run()` rejects only for setup problems,** with a `CliError` whose `type` is one of:
+  - `not-found` — the executable is not on `PATH`;
+  - `capability` — `--help` lacks a needed flag; the error carries `flag` and `version`;
+  - `probe-failed` — the CLI's help could not be read;
+  - `unsupported-option` — the adapter cannot honour an option;
+  - `prompt-transport` — the prompt fits neither argv nor stdin.
+
+`ai.cli` is the same namespace once `import "@warlock.js/ai-cli"` has run.
+
+## Resume, cancel, time out
+
+```ts
+import { cli } from "@warlock.js/ai-cli";
+
+const codex = cli.codex({ cwd: "/srv/acme-api" });
+const plan = await (await codex.run("Plan the billing refactor; do not edit files")).done();
+
+const controller = new AbortController();
+const step = await codex.run("Implement step 1 of the plan", {
+  resume: plan.sessionRef,
+  signal: controller.signal,
+  timeoutMs: 15 * 60_000,
+});
+
+setTimeout(() => controller.abort(), 60_000); // or step.cancel()
+
+const outcome = await step.done();
+
+console.log(outcome.status); // "cancelled" after the abort
+```
+
+Abort and timeout kill the whole process tree. On POSIX that is the CLI's process group (SIGTERM, then SIGKILL after `killGraceMs`, default 2000); on Windows it is `taskkill /T /F` on its PID. A run whose signal is already aborted never spawns.
+
+## Permissions — bypass is opt-in
+
+```ts
+import { cli } from "@warlock.js/ai-cli";
+
+// Default "standard": the CLI's own non-interactive rules; anything needing approval is refused.
+const reviewer = cli.copilot({ cwd: "/srv/acme-api" });
+
+// "bypass": every tool call approved without asking. Only for a sandboxed run.
+const fixer = cli.grok({ cwd: "/sandbox/acme-api", permission: "bypass" });
+
+const review = await (await reviewer.run("Review src/billing for bugs")).done();
+const fix = await (
+  await fixer.run("Apply the fixes from the review", { permission: "bypass" })
+).done();
+
+console.log(review.text, fix.status);
+```
+
+What `"standard"` allows depends on the vendor:
+
+- **Read-only:** Codex and Droid. Allow edits with `args: ["-c", "sandbox_mode=workspace-write"]` (Codex) or `args: ["--auto", "medium"]` (Droid).
+- **Permissive:** OpenCode and Amp.
+- **Refused:** Kimi Code always approves in print mode, so its adapter rejects `"standard"` and needs `"bypass"`.
+
+## MCP servers, secrets and homes
+
+```ts
+import { cli } from "@warlock.js/ai-cli";
+
+const claude = cli.claudeCode({
+  apiKey: process.env.ANTHROPIC_API_KEY, // exported as ANTHROPIC_API_KEY, never argv
+  inheritEnv: ["GITHUB_TOKEN"], // minimal system env + these names only
+});
+
+const session = await claude.run("Triage the open issues", {
+  mcp: {
+    tracker: {
+      type: "stdio",
+      command: "npx",
+      args: ["-y", "@acme/tracker-mcp"],
+      env: { TRACKER_TOKEN: process.env.TRACKER_TOKEN ?? "" },
+    },
+    docs: {
+      type: "http",
+      url: "https://mcp.acme.dev/mcp",
+      headers: { Authorization: `Bearer ${process.env.DOCS_TOKEN ?? ""}` },
+    },
+  },
+});
+
+console.log((await session.done()).text);
+```
+
+**MCP servers.** They are written as a mode-0600 file inside a private per-run directory (mode 0700), never into argv, and the file is removed after the run. CLIs that read MCP only from their config home (Kimi, Grok, Cursor, Droid, Antigravity, Mistral Vibe, Reasonix) need the default private home. Aider has no MCP support.
+
+**Homes.** The `home` option takes one of:
+
+- `"private"` (default) — a fresh config home per run;
+- an absolute path — a home you own, for example one you logged in to;
+- `"inherit"` — your normal config.
+
+The adapter's home variable (`CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `COPILOT_HOME`, `GROK_HOME`, …) is pointed at it.
+
+## Use a CLI as an `ai.agent` model
+
+```ts
+import { ai, budget } from "@warlock.js/ai";
+import { cli } from "@warlock.js/ai-cli";
+
+const coder = cli.codex({ cwd: "/srv/acme-api" });
+
+const reviewer = ai.agent({
+  model: coder.model({ name: "codex-reviewer" }),
+  middleware: [budget({ maxTokens: 200_000 })],
+});
+
+const review = await reviewer.execute("Review the last commit for bugs.");
+
+console.log(review.text, review.usage.total);
+```
+
+How the model behaves:
+
+- **One fresh CLI session per call.** System messages lead the prompt, and a history is rendered as a transcript.
+- **The CLI uses its own tools.** A call with agent `tools` is refused; give the CLI `mcp` servers instead.
+- **Streaming yields the final answer once the session ends.**
+- **A failed run throws `CliError` with `type: "run-failed"`,** so `fallbackModel` works.
+- **Pass `pricing`** for USD cost.
+
+## Pitfalls
+
+- Install and log in to the vendor CLI yourself. With the default private home, authenticate with `apiKey`/`env`.
+- `effort` is refused by CLIs without an effort control (Qwen Code, Kimi, Cursor, Mistral Vibe), and `model` is refused by Amp. Nothing is silently ignored.
+- `args` is passed verbatim; never put a token there.
+- The vendor table in the docs ("Vendor adapters") lists each CLI's flags, stream format, and the version it was verified against.