acpx

library0.5.3jsnpmunverified

A headless CLI client for the Agent Client Protocol (ACP), enabling AI agents and orchestrators to communicate with coding agents via structured protocol commands instead of PTY scraping. Current stable version: 0.5.3 (alpha). Released frequently with breaking changes expected until stabilization. Supports persistent multi-turn sessions, named sessions, prompt queueing, cooperative cancellation, soft-close lifecycle, crash reconnect, fire-and-forget mode, config files, session inspect/history, and experimental TypeScript-based workflows. Key differentiator: agent-to-agent communication over CLI without ANSI parsing, with compatibility for multiple ACP-compatible agents (Codex, Claude, OpenClaw ACP). Requires Node.js >=22.12.0.

http-networking llm-agents devops

npm install acpx

github ↗package ↗

INSTALL

IMPORT

SIG · ACPX

acpx

http-networkingjavascriptv0.5.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default (library import)

✓ import acpx from 'acpx'

✗ const acpx = require('acpx')

acpx is ESM-only since v0.1.0; CommonJS require will fail. Use dynamic import if needed: await import('acpx')

defineFlow

✓ import { defineFlow } from 'acpx/runtime'

✗ import { defineFlow } from 'acpx'

defineFlow is exported from the runtime embedding entry point, not the main module. Exported since v0.5.0.

FlowContext

✓ import type { FlowContext } from 'acpx/runtime'

✗ import { FlowContext } from 'acpx/runtime'

FlowContext is a TypeScript type; use 'import type' to avoid runtime issues. Available since v0.5.0.

Demonstrates creating a persistent session, sending prompts, named sessions for parallel work, fire-and-forget mode, and soft-close lifecycle.

import acpx from 'acpx'; // Start a session with Codex agent (requires CODEX_API_KEY env variable) const session = await acpx.sessions.create({ agent: 'codex', name: 'my-session' }); // Send a prompt and get structured response const response = await session.prompt('Explain async/await in JavaScript'); console.log(response.thinking); console.log(response.toolCalls); // Use named sessions for parallel work const frontendSession = await acpx.sessions.create({ agent: 'codex', name: 'frontend' }); const backendSession = await acpx.sessions.create({ agent: 'codex', name: 'backend' }); await frontendSession.prompt('Create React component'); await backendSession.prompt('Add API endpoint'); // Fire-and-forget without waiting for completion acpx.sessions.send('my-session', { prompt: 'Run tests', noWait: true }); // Close session softly await session.close();

acp --version

Debug

Known issues

breakingAPI surface is in alpha and may change significantly between minor versions. Anything built downstream may break until v1.0.0 stabilizes.

fix

Pin exact version in package.json and monitor changelog for breaking changes.

affects: <1.0.0

breakingdefineFlow is now required for flow definitions as of v0.5.0. Raw flow objects are no longer accepted.

fix

Wrap flow definitions with defineFlow().

affects: >=0.5.0

deprecatedThe `codex` adapter path may change; `codex` is currently an alias and may be renamed in future versions.

fix

Use the fully qualified agent name or check adapter registry with acpx config.

affects: >=0.5.0

gotchaNode.js >=22.12.0 is required. Using older Node versions will result in runtime errors due to ESM features and internal dependencies.

fix

Upgrade Node.js to v22.12.0 or higher.

affects: >=0.1.0

gotchaSession history is stored on disk by default; soft-close does not delete history. For clean state, use session.delete() or delete the session directory manually.

fix

Call session.delete() instead of session.close() to remove persisted history.

affects: >=0.1.0

deprecatedThe experimental flow runtime (acpx flow run) API is unstable and may change in v0.6.x without notice.

fix

Use with caution; follow the runtime embedding API changes in changelog.

affects: >=0.4.0 <0.6.0

Errors

Common errors & fixes

Cannot find module 'acpx'

Using CommonJS require() instead of ESM import.

fix

Replace 'const acpx = require("acpx")' with 'import acpx from "acpx"' in an ESM context, or use dynamic import: `const acpx = await import('acpx')`.

Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/acpx/... from ... not supported.

acpx is an ESM-only package; CommonJS require is not allowed.

fix

Switch to ESM by adding 'type': 'module' in package.json or use dynamic import.

TypeError: flow(...) is not a function

Flow definition not wrapped with `defineFlow` as required since v0.5.0.

fix

Wrap your flow object with `defineFlow(flow)` from 'acpx/runtime'.

Error: Unknown agent: 'codex'. Available built-in adapters: ...

Agent name mismatch or missing adapter configuration.

fix

Check available agents with `acpx config show` or provide full path via --agent option.

Upgrade

Version history

0.5.3latest on npm

Audit

Dependencies

@agentclientprotocol/sdkrequiredCore SDK dependency for ACP protocol handling and session management

Agent activity

71 hits · last 30 days

node

Perplexity

OpenAI (training)

Resources

githubhttps://github.com/openclaw/acpx ↗

packagehttps://www.npmjs.com/package/acpx ↗