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-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.
• 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.

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

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.

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. 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.

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-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-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-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,
  codexSandboxMode: "workspace-write",
});

Notes:

• CLI adapters accept container or sandbox, but not both
• claude-cli-pty runs socat through the execution target, so socat must be available inside the container or sandbox environment
• claude-cli-pty writes per-run Stop hook files under the sandbox workdir, so that workdir must be writable
• claude-cli-pty examples that need file edits establish those permissions up front with permissionMode or allowedTools; onPermissionRequest is intended for remaining interactive prompts such as Bash approvals
• 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 uses codexSandboxMode for the Codex CLI --sandbox flag so it does not conflict with 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