The modern developer's terminal has become a crowded marketplace of competing AI agents. In a single afternoon, a lead engineer might jump from Cursor for architectural drafting to Claude Code for deep refactoring, then switch to GitHub Copilot for boilerplate generation. While each tool offers distinct strengths, they operate as isolated silos with proprietary interfaces and divergent execution patterns. This fragmentation creates a hidden tax on productivity, forcing developers to manage multiple contexts and disparate configuration files just to keep their AI assistants aligned with their local environment.
The Architecture of spawn-agent and the ACP Standard
To solve this fragmentation, spawn-agent emerges not as another competing agent, but as a sophisticated adapter layer. Its primary objective is to wrap local coding agents within a standardized interface, specifically hiding them behind the LanguageModelV3 interface of the Vercel AI SDK. By doing so, it allows developers to invoke various local tools as if they were a single, unified model. The technical foundation of this project is the Agent Client Protocol (ACP), an open specification designed to standardize communication between agents and clients. Rather than inventing a proprietary handshake, spawn-agent implements ACP using JSON-RPC messages delivered via NDJSON (Newline Delimited JSON) over standard input and output (Standard I/O).
The project is organized as a pnpm monorepo, which separates the core library from its demonstration environments. This structure includes deterministic ACP fixtures for rigorous testing and a WebSocket bridge to facilitate real-time, bidirectional communication. The compatibility list is broad: CLI tools that natively support ACP, such as Cursor, Gemini, OpenCode, Droid, and Pi, can be connected immediately. For tools that do not yet adhere to the standard, such as Claude Code and Codex, spawn-agent utilizes dedicated conversion packages to translate their outputs into the ACP format. To run this environment, the system requires Node 22 or higher and pnpm 8 or higher, operating alongside the `ai@^6.0.0` package.
Moving Beyond Simple Wrappers to Operational Governance
While the ability to unify interfaces is useful, the true shift occurs in how spawn-agent handles the operational lifecycle of these agents. Most wrappers simply pass strings back and forth, but spawn-agent introduces a rigorous session management policy. It supports two distinct execution modes: a one-off mode that spawns a fresh process for every call, and a session mode that maintains a persistent process to preserve conversation memory. To prevent the common pitfall of zombie processes in Node.js, the session object implements the AsyncDisposable interface. This allows developers to use the `await using` syntax, ensuring that resources are released and processes are terminated safely without manual cleanup.
This governance extends to the process level. spawn-agent strictly manages child process output, blocking noise from standard output while preserving only the final segment of standard error to assist in diagnostics during abnormal terminations. The shutdown sequence is equally disciplined: the system issues a SIGTERM signal, waits for a two-second grace period, and then executes a SIGKILL to ensure the process is fully purged. Furthermore, the tool introduces a granular permission negotiation system to mitigate the security risks of giving AI agents terminal access. Developers can choose from four predefined presets: `auto-allow`, `auto-allow-once`, `auto-reject`, and `stream`, or define custom response logic via functions. To minimize the attack surface, capabilities like filesystem or terminal access are only advertised as ACP abilities when the host provides a corresponding handler. This is supported by a hierarchical error classification system featuring 16 distinct error types, enabling the calling application to implement precise retry policies based on the nature of the failure.
By treating local AI agents as managed infrastructure rather than standalone utilities, spawn-agent shifts the focus from tool acquisition to tool orchestration. It effectively lowers the integration cost for development teams by layering professional operational policies over existing CLI assets.
