coding-agents-sdk

This is a coding agent orchestration library.

Install

bun add coding-agents-sdk

If you use an SDK adapter or the e2b container provider, install that optional peer too.

# for claude-code-sdk
bun add @anthropic-ai/claude-agent-sdk

# for codex-sdk
bun add @openai/codex-sdk

# for createContainer({ type: "e2b", ... })
bun add e2b

Runtime setup

Before you call await createAgent(...), make sure the runtime for that adapter is available.

• claude-code-cli runs Claude Code CLI.
• claude-code-cli-pty runs interactive Claude Code behind a PTY and requires socat on PATH.
• claude-code-sdk uses @anthropic-ai/claude-agent-sdk and launches Claude Code locally.
• codex-cli runs Codex CLI.
• codex-sdk uses @openai/codex-sdk and launches Codex locally.
• cursor-cli runs Cursor CLI.
• cursor-sdk uses @cursor/sdk and launches Cursor locally.
• gemini-cli runs Gemini CLI.
• opencode-cli runs OpenCode CLI.
• pi-cli runs Pi CLI.

SDK adapters and the e2b container provider are optional peer dependencies. Install only the ones you use.

If one is missing, createAgent(), createContainer(), or the first run() surfaces an error that tells you which package to install.

Set cwd when the agent should run somewhere other than the current working directory.

Use agent.capabilities when you need to branch on features at runtime.

Option names shared across adapters (like permissionMode) take adapter-specific values — check the adapter's *RunOptions type for the valid set.

Claude and Codex CLI both keep automatic review separate from dangerous bypass:

• Claude "auto" and Codex CLI "auto-approve" use model-based review to approve or deny permission requests; Codex uses its workspace-write sandbox
• Claude "bypassPermissions" and Codex CLI "bypass-sandbox" disable permission checks; the Codex mode also disables its sandbox

Use bypass modes only when execution is externally isolated, such as inside a container.

Quick start

import { createAgent } from "coding-agents-sdk";

await using agent = await createAgent("claude-code-cli");

const result = await agent.run({
  input: "Read package.json and tell me what this project does.",
});

if (result.status !== "completed") {
  throw new Error(result.error.message);
}

console.log(result.text);

Replace "claude-code-cli" with the adapter you want to use. Unless noted otherwise, the rest of the snippets assume the same agent shape.

Run results

run() returns a RunResult with status: "completed" | "failed" | "cancelled".

const result = await agent.run({
  input: "Review the last commit.",
});

switch (result.status) {
  case "completed":
    console.log(result.text);
    break;
  case "failed":
    console.error(result.error.kind, result.error.message);
    break;
  case "cancelled":
    console.error(result.cancelReason, result.error.message);
    break;
}

If you just want the completed result and treat any non-completion as an error, use runOrThrow():

// throws AgentRunError if the run is cancelled or fails
const result = await agent.runOrThrow({ input: "Review the last commit." });
console.log(result.text);

Notes:

• runOrThrow() turns non-completed runs into AgentRunError
• stop(), wait(), reset(), and dispose() are available on every agent

TypeScript infers the completed-result shape from your request:

• Zod schema: result.output is fully typed
• raw JSON Schema: result.output is unknown
• no schema: use result.text; completed results do not include output
• runOrThrow() follows the same inference, but only returns the completed variant

Input

Most calls just use a string. If you need richer input, pass parts instead.

claude-code-cli and codex-cli send prompt text through stdin rather than command-line arguments, including when resuming a session.

Image input is currently supported by codex-sdk and pi-cli.

await using agent = await createAgent("codex-sdk");

await agent.run({
  input: [
    { type: "text", text: "Describe this image." },
    { type: "image", path: "./ui.png" },
  ],
});

Structured output

Pass schema when you want structured output.

If you want typed output, pass a Zod schema. If you pass raw JSON Schema, result.output is unknown. If you do not pass a schema, use result.text.

import { z } from "zod/v4";

const result = await agent.run({
  input: "Read package.json and return the package name and whether it has a test script.",
  schema: z
    .object({
      name: z.string(),
      hasTestScript: z.boolean(),
    })
    .strict(),
});

if (result.status === "completed") {
  console.log(result.output);
}

If you want to pass Zod schemas, depend on zod in your app.

schema accepts a raw JSON Schema object or a Zod schema. This wrapper validates only the Zod path. cursor-cli, cursor-sdk, gemini-cli, opencode-cli, and pi-cli do not support structured output.

If you need to name these shapes in your own helpers, import RunRequest, JsonSchemaRunRequest, ZodRunRequest, RunResult, or CompletedRunResult from the package.

Sessions

One agent instance keeps one conversation going. Reuse the same instance when you want the next turn to continue the same session.

await agent.run({
  input: "Remember this word: pineapple. Reply with only 'ok'.",
});

const result = await agent.run({
  input: "What word did I ask you to remember?",
});

Useful bits:

• agent.sessionId is set once a session exists
• pass sessionId to await createAgent(type, { sessionId }) to resume one explicitly
• reset() forgets the stored session
• Claude adapters and pi-cli support fork()

Events

Use onEvent() to subscribe to the normalized event stream.

const unsubscribe = agent.onEvent((event) => {
  if (event.type === "tool-call") {
    console.log(event.toolName);
  }
});

await agent.run({
  input: "Explain the package layout.",
});

unsubscribe();

All adapters emit session-start and session-end. Depending on the backend, you may also see message, reasoning, tool-call, tool-result, and stderr.

Provider events

Use onProviderEvent() on claude-code-cli or codex-cli for provider-specific details not included in normalized events.

import { createClaudeCodeCliAgent } from "coding-agents-sdk/adapters/claude-code-cli";

await using claude = createClaudeCodeCliAgent();
const unsubscribe = claude.onProviderEvent(({ runId, sessionId, event }) => {
  if (event.type === "system" && event.subtype === "init") {
    console.log(runId, sessionId, event.tools, event.mcp_servers);
  }
});

await claude.run({ input: "Explain the package layout." });
unsubscribe();

For Codex, import createCodexCliAgent from coding-agents-sdk/adapters/codex-cli.

Provider events are not stored in RunResult.events; collect them in your callback if needed. Subscriptions persist across runs and reset(). Subscribe separately on forked agents.

Custom process launchers

Wrap spawnProcess with a ProcessSpawner to customize how a CLI agent launches:

import { spawnProcess, type ProcessSpawner } from "coding-agents-sdk/process";

const spawner: ProcessSpawner = {
  spawn(command, args, options) {
    const child = spawnProcess(command, args, options);
    console.log("Agent process launched");
    return child;
  },
};

Pass spawner when creating a CLI agent. For claude-code-cli and codex-cli, the returned process must provide stdin.write and stdin.end.

Stdin methods may complete synchronously or return Promise<void>; agents await their completion. Built-in spawners observe rejected write/EOF promises and retain the failure for wait(), so ignoring an operation's return value does not create a separate unhandled rejection.

Stdin failures reported by wait() use ProcessStdinError, exported from the root and coding-agents-sdk/process, with the original error in cause. Custom spawners should use this error for that case so agents distinguish delivery failures from launch failures. Awaiting a built-in stdin operation still rejects with its original error.

MCP

MCP tool calls can show up in the event stream when the underlying runtime supports them.

This wrapper exposes MCP configuration directly on:

• claude-code-cli: mcpConfig, mcpServers
• claude-code-cli-pty: mcpConfig, mcpServers
• claude-code-sdk: mcpServers
• codex-cli: mcpConfig, mcpServers
• opencode-cli: MCP is supported by the runtime (configure via opencode's own settings)

For codex-sdk, gemini-cli, and pi-cli, use the runtime's own MCP setup. This wrapper does not add separate MCP config options for them.

Containers

Containers are supported on the CLI adapters: claude-code-cli, claude-code-cli-pty, codex-cli, gemini-cli, opencode-cli, and pi-cli. Built-in container providers are:

• docker
• podman
• nerdctl
• e2b

docker, podman, and nerdctl do not need extra package dependencies from this SDK. e2b requires the optional e2b peer dependency.

import { createAgent, createContainer } from "coding-agents-sdk";

await using container = await createContainer({
  type: "docker",
  workdir: "/workspace",
  image: "my-agent-image",
  // or instead of image:
  // build: {
  //   content: [
  //     "FROM ubuntu:24.04",
  //     "RUN apt-get update && apt-get install -y --no-install-recommends ca-certificates curl git && rm -rf /var/lib/apt/lists/*",
  //     "RUN useradd -m -s /bin/bash agent",
  //     "USER agent",
  //     "RUN curl -fsSL https://claude.ai/install.sh | bash",
  //     'ENV PATH="/home/agent/.local/bin:${PATH}"',
  //     "WORKDIR /workspace",
  //   ].join("\n"),
  // },
  mounts: [{ source: "/absolute/path/to/project", target: "/workspace" }],
});

await using agent = await createAgent("claude-code-cli", {
  container,
  permissionMode: "bypassPermissions",
});

const result = await agent.run({
  input: "Run the tests and fix the failing test.",
});

if (result.status === "completed") {
  console.log(result.text);
}

Your image needs the runtime for the adapter you picked available inside the container. For claude-code-cli-pty, install both claude and socat in the image; the Stop hook also expects sh and cat.

If you omit cwd, the agent uses container.workdir. The container is started automatically on the first run. Use snapshotWorkdir(), diffWorkdir(), and releaseWorkdirSnapshot() when you need a reliable before/after file diff.

propagateEnv defaults depend on the execution target:

• local CLI runs propagate the host env by default
• sandbox-backed CLI runs also propagate the host env by default
• container-backed CLI runs default propagateEnv to false so host PATH and other runtime vars do not override the container environment during exec
• env still applies in every case
• set propagateEnv: true on a container-backed agent only when you intentionally want host env passed through to docker exec / podman exec / nerdctl exec

Notes:

• nerdctl reuses the same OCI-backed behavior as docker and podman, but it depends on a working containerd and BuildKit setup on the host; the bundled nerdctl examples use network: "host" to avoid rootless CNI/firewall differences across hosts
• for nerdctl, prefer passing address, namespace, and buildkitHost explicitly when you depend on a non-default or rootless local runtime, rather than relying on ambient shell env

Sandboxes

For non-container execution targets, create a sandbox and pass it as sandbox.

import { createAgent, createSandbox } from "coding-agents-sdk";

await using sandbox = await createSandbox({
  type: "bubblewrap",
  workdir: process.cwd(),
  setEnv: {
    OPENAI_API_KEY: process.env.OPENAI_API_KEY ?? "",
  },
});

await using agent = await createAgent("codex-cli", {
  sandbox,
  sandboxMode: "workspace-write",
});

Notes:

• CLI adapters accept container or sandbox, but not both
• claude-code-cli-pty runs socat through the execution target, so socat must be available inside the container or sandbox environment
• claude-code-cli-pty writes per-run Stop and PermissionRequest hook files to its run directory; sandbox-backed runs place that directory under the sandbox workdir, so it must be writable
• claude-code-cli-pty supports onPermissionRequest through a run-local Claude PermissionRequest hook and does not parse terminal permission prompts; the generated --settings payload contains only SDK hook entries so Claude can merge it with existing user and project hooks
• claude-code-cli-pty container runs cannot use onPermissionRequest because the generated hook calls a host loopback bridge that is not reachable from the container network namespace
• sandbox-backed CLI runs keep the normal propagateEnv default and inherit the host env unless you set propagateEnv: false
• built-in sandbox providers are bubblewrap, firejail, and nsjail
• codex-cli's sandboxMode sets the Codex CLI --sandbox policy only when permissionMode is omitted or "default"; it is independent of the sandbox execution target option
• if you omit cwd, the agent uses sandbox.workdir
• keep network access enabled when the sandboxed CLI still needs to reach a hosted model API
• firejail and nsjail are Linux-only and depend on the corresponding host binaries and kernel features being available
• nsjail preserves PATH by default so relative adapter commands still launch, but other host env vars remain cleared unless you opt back in with clearEnv: false
• bubblewrap and nsjail commonly use a private or remounted /tmp; if the host process writes helper files that the sandboxed CLI must read, you probably want to bind-mount /tmp or another host temp directory there
• firejail is more host-dependent than bubblewrap; readOnly plus readWrite tune path permissions inside Firejail's base filesystem, while allowlist-style confinement needs explicit whitelist / blacklist rules. Setting a synthetic HOME only redirects CLI state files; it does not hide the real host home by itself
• in particular, codex-cli structured output (schema) and claude-code-cli mcpServers create helper files that should live on a sandbox-visible /tmp