acp-client

Standalone ACP client helpers for launching and talking to Agent Client Protocol agents.

Package Surfaces

• acp-client
  • Runtime-neutral ACP stream, connection, session, and registry types.
• acp-client/node
  • Node stdio process launching, registry cache integration, and binary install helpers.

See docs/api.md for a compact public API map.

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()
}

See examples for runnable Node and inline registry examples.

For supported ACP surfaces, host-owned behavior, and deferred protocol areas, see Protocol Coverage.

Dependency Posture

This package keeps runtime dependencies intentionally small. Archive extraction dependencies are exact-pinned in package.json and chosen to avoid transitive runtime dependencies where practical:

• modern-tar
• @ckirby/unbzip2-multistream
• node-stream-zip

These packages are used for .tar.gz, .tar.bz2, and .zip binary archive installs. Keeping them exact-pinned and zero-transitive reduces supply-chain exposure in the archive installation path. The acp-client maintainers also use two-factor authentication for package maintenance accounts.

Registry Fallback

The Node entrypoint includes a generated fallback copy of the upstream ACP registry so known agents can still resolve when a registry clone is unavailable.

Cache Locations

The Node entrypoint stores package-owned caches under XDG_CACHE_HOME when it is 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 when they need isolated caches 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",
})

License

This project is licensed under the MIT License.