Use this package when you want to launch an ACP agent from a registry id or inline distribution manifest, connect over stdio, and work with a small typed client instead of wiring JSON-RPC streams by hand.

Fit

acp-client is a good fit for:

Node-based hosts that need to launch registry-backed ACP agents such as codex-acp.
Hosts that already manage an ACP transport and want runtime-neutral session helpers.
SDKs that accept either common ACP registry ids or caller-provided agent distributions.
Integrations that want Node filesystem or terminal callbacks matching advertised ACP client capabilities.

It is not a good fit when you need:

A full chat transcript, timeline reducer, permission UI, or persistence layer.
Browser-native ACP transport helpers.
A registry validator that rejects unknown ids at compile time or runtime.
A framework-specific React, Vue, Electron, or CLI application shell.

Requirements And Tradeoffs

Runtime: Node.js 18 or newer.
Module format: ESM.
Peer dependency: zod v3.25 or v4.
Transport: the high-level Node client launches stdio agents; lower-level helpers accept already-open streams.
Registry ids remain open strings. AcpAdapterId improves autocomplete for bundled ids but still accepts custom or newly published ids.

The package deliberately stays close to ACP protocol shapes. You get a typed connection/session layer, registry launch support, and optional Node host callbacks, but application policy and user experience remain host-owned.

Install

npm install acp-client zod

Minimal Launch

This example demonstrates the primary value path: launch a known registry adapter, create a session, send a prompt, and close the managed process.

import { createNodeAcpClient } from "acp-client/node"

const client = await createNodeAcpClient({
  agent: "codex-acp",
  cwd: process.cwd(),
  clientInfo: {
    name: "example-client",
    version: "1.0.0",
  },
  handler: {
    async requestPermission() {
      return { outcome: { outcome: "cancelled" } }
    },
    async sessionUpdate(params) {
      console.log(params)
    },
  },
})

try {
  const session = await client.newSession({
    cwd: process.cwd(),
    mcpServers: [],
  })
  await session.prompt("Hello from ACP")
} finally {
  await client.close()
}

Adapter Id Types

Use AcpAdapterId when downstream SDKs should autocomplete bundled registry ids while still accepting custom registry entries.

import { knownAcpAdapterIds, type AcpAdapterId, type AgentDistribution } from "acp-client"

export type AgentInput = AcpAdapterId | AgentDistribution

knownAcpAdapterIds is generated from the package's bundled registry fallback at build time and is available from the browser-safe main entry point. Runtime resolution still goes through createAcpRegistryService() or createNodeAcpClient() from acp-client/node.

Package Surfaces

Use the root entry point for code that may run in browsers, webviews, Electron renderers, or other runtimes where Node built-ins are unavailable:

import {
  AdapterCatalogEntry,
  createAcpClient,
  knownAcpAdapterIds,
  type AcpAdapterId,
  type AgentDistribution,
} from "acp-client"

acp-client exports the runtime-neutral client/session layer, stream transport helpers, adapter catalog metadata, and Zod schemas for validating agent distribution manifests. Its module graph is browser-safe and centered on shared ACP types, schemas, and transport primitives.

Use acp-client/node only from Node runtimes that need to launch agents or manage local host integrations:

import {
  createAcpRegistryService,
  createNodeAcpClient,
  createNodeFileSystemClientHandler,
  createNodeTerminalClientHandler,
} from "acp-client/node"

acp-client/node adds registry cache synchronization, stdio process launching, binary archive installation, and filesystem or terminal client handlers. It re-exports the root acp-client surface for compatibility, but browser and webview bundles should import shared schemas and adapter metadata from acp-client.

Use acp-client/protocol when you need direct access to curated ACP SDK protocol constants, request errors, NDJSON framing, or protocol types without importing the higher-level client helpers:

import { PROTOCOL_VERSION, RequestError, type SessionNotification } from "acp-client/protocol"

See docs/api.md for the compact public API map and examples for runnable Node and inline registry examples.

Registry Fallback And Caches

The Node entry point includes a generated fallback copy of the upstream ACP registry so bundled agents can still resolve when a registry clone is unavailable. It stores package-owned caches under XDG_CACHE_HOME when set, otherwise under the user's home cache directory:

Registry clone: $XDG_CACHE_HOME/acp-client/registry or ~/.cache/acp-client/registry
Downloaded binaries: $XDG_CACHE_HOME/acp-client/binaries or ~/.cache/acp-client/binaries

Hosts can override those paths for CI, tests, or sandboxed runtimes:

import { createAcpRegistryService, createNodeAcpClient } from "acp-client/node"

const registryService = createAcpRegistryService({
  cacheDir: "/tmp/acp-client/registry",
})

const client = await createNodeAcpClient({
  agent: "codex-acp",
  cwd: process.cwd(),
  clientInfo: {
    name: "example-client",
    version: "1.0.0",
  },
  registryService,
  binaryCacheDir: "/tmp/acp-client/binaries",
})