spawn_agent
Launch an AI agent in a new terminal window to execute tasks using specified models and CLI tools. Configure with repository, model selection, and task prompt for immediate deployment.
Instructions
Spawn an AI agent in a new terminal surface. Returns immediately — use wait_for to block until ready.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | Repository name (e.g. 'brainlayer', 'golems') | |
| model | Yes | Model name (e.g. 'sonnet', 'codex', 'opus') | |
| cli | Yes | CLI tool to launch | |
| prompt | Yes | Task prompt to send after agent is ready | |
| workspace | No | Target workspace ref |
Implementation Reference
- src/agent-engine.ts:317-340 (handler)The core implementation of the agent spawning logic.
async spawnAgent(params: SpawnAgentParams): Promise<SpawnAgentResult> { const agentId = generateAgentId(params.model, params.repo); // Resolve parent hierarchy let spawnDepth = 0; let parentAgentId: string | null = null; if (params.parent_agent_id) { const parent = this.registry.get(params.parent_agent_id); if (!parent) { throw new Error(`Parent agent not found: ${params.parent_agent_id}`); } if (parent.spawn_depth >= MAX_SPAWN_DEPTH) { throw new Error(`Max spawn depth exceeded: ${MAX_SPAWN_DEPTH}`); } const children = this.registry.getChildren(params.parent_agent_id); if (children.length >= MAX_CHILDREN) { throw new Error(`Max children exceeded: ${MAX_CHILDREN}`); } spawnDepth = parent.spawn_depth + 1; parentAgentId = params.parent_agent_id; } // 1. Create cmux surface - src/server.ts:684-714 (registration)Registration of the 'spawn_agent' MCP tool and its invocation handler in server.ts.
server.tool( "spawn_agent", "Spawn an AI agent in a new terminal surface. Returns immediately — use wait_for to block until ready.", { repo: z .string() .describe("Repository name (e.g. 'brainlayer', 'golems')"), model: z .string() .describe("Model name (e.g. 'sonnet', 'codex', 'opus')"), cli: z .enum(["claude", "codex", "gemini", "kiro", "cursor"]) .describe("CLI tool to launch"), prompt: z.string().describe("Task prompt to send after agent is ready"), workspace: z.string().optional().describe("Target workspace ref"), }, async (args) => { try { const result = await engine.spawnAgent({ repo: args.repo, model: args.model, cli: args.cli, prompt: args.prompt, workspace: args.workspace, }); return ok({ ...result }); } catch (e) { return err(e); } }, ); - src/agent-engine.ts:20-28 (schema)Parameter definition for the spawnAgent operation.
export interface SpawnAgentParams { repo: string; model: string; cli: CliType; prompt: string; workspace?: string; parent_agent_id?: string; max_cost_per_agent?: number; }