spawn-agent

Spawn available local agents on an user's computer

A Vercel AI SDK provider for Claude Code, Codex, Cursor, GitHub Copilot, Gemini, OpenCode, Factory Droid, and Pi — streamed over the Agent Client Protocol.

Install

npm install spawn-agent ai

Usage

import { streamText } from "ai";
import { spawnAgent } from "spawn-agent";

const { textStream } = streamText({
  model: spawnAgent("claude"),
  prompt: "Refactor src/auth.ts to use the new session API",
});

for await (const chunk of textStream) {
  process.stdout.write(chunk);
}

Pass settings inline at the call site, or build a pre-configured provider with createSpawnAgent:

import { generateText } from "ai";
import { spawnAgent } from "spawn-agent";

const { text } = await generateText({
  model: spawnAgent("codex", {
    cwd: "/Users/me/project",
    permission: "auto-allow",
    mcpServers: [
      {
        type: "stdio",
        name: "filesystem",
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      },
    ],
  }),
  prompt: "Summarize README.md in three bullets",
});

Setting	Effect
cwd	Working directory the agent operates in.
permission	"auto-allow" (default) / "auto-allow-once" / "auto-reject" / "stream".
mcpServers	MCP server configs the agent connects to for extra tools.
additionalDirectories	Extra absolute paths the agent can read/write.
systemPrompt	Prepended to user prompts.
inactivityTimeoutMs	Kill the turn if the agent goes silent (default 3 min).

Supported agents

ID	Display name	Notes
claude	Claude Code	requires @agentclientprotocol/claude-agent-acp
codex	Codex	requires @zed-industries/codex-acp
cursor	Cursor Agent	native ACP
copilot	GitHub Copilot CLI	native ACP
gemini	Gemini CLI	native ACP
opencode	OpenCode	native ACP
droid	Factory Droid	native ACP
pi	Pi	native ACP

For a custom ACP-speaking subprocess, use spawnAgent.fromAdapter(...).

Stateful sessions

For multi-turn conversations on a single subprocess, use createSpawnAgentSession. Each streamText call against session.model sends one session/prompt turn, so the agent's conversation memory is preserved across turns:

import { streamText } from "ai";
import { createSpawnAgentSession } from "spawn-agent";

await using session = await createSpawnAgentSession("codex");

await streamText({ model: session.model, prompt: "list TODOs" });
await streamText({ model: session.model, prompt: "now fix the highest one" });

// slash commands via providerOptions
await streamText({
  model: session.model,
  prompt: "agent client protocol",
  providerOptions: { spawnAgent: { command: "web" } },
});

For human-in-the-loop permission prompts, terminal handlers, and session resume, the session.agent field exposes the underlying SpawnAgent. See packages/spawn-agent/src/index.ts for the full API.

Contributing

Contributing Guide · Issues

License

MIT