{"id":18089,"library":"acpx","title":"acpx","description":"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.","status":"active","version":"0.5.3","language":"javascript","source_language":"en","source_url":"https://github.com/openclaw/acpx","tags":["javascript","acp","agent-client-protocol","ai","claude-code","cli","codex","coding-agent"],"install":[{"cmd":"npm install acpx","lang":"bash","label":"npm"},{"cmd":"yarn add acpx","lang":"bash","label":"yarn"},{"cmd":"pnpm add acpx","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core SDK dependency for ACP protocol handling and session management","package":"@agentclientprotocol/sdk","optional":false}],"imports":[{"note":"acpx is ESM-only since v0.1.0; CommonJS require will fail. Use dynamic import if needed: await import('acpx')","wrong":"const acpx = require('acpx')","symbol":"default (library import)","correct":"import acpx from 'acpx'"},{"note":"defineFlow is exported from the runtime embedding entry point, not the main module. Exported since v0.5.0.","wrong":"import { defineFlow } from 'acpx'","symbol":"defineFlow","correct":"import { defineFlow } from 'acpx/runtime'"},{"note":"FlowContext is a TypeScript type; use 'import type' to avoid runtime issues. Available since v0.5.0.","wrong":"import { FlowContext } from 'acpx/runtime'","symbol":"FlowContext","correct":"import type { FlowContext } from 'acpx/runtime'"}],"quickstart":{"code":"import acpx from 'acpx';\n\n// Start a session with Codex agent (requires CODEX_API_KEY env variable)\nconst session = await acpx.sessions.create({\n  agent: 'codex',\n  name: 'my-session'\n});\n\n// Send a prompt and get structured response\nconst response = await session.prompt('Explain async/await in JavaScript');\nconsole.log(response.thinking);\nconsole.log(response.toolCalls);\n\n// Use named sessions for parallel work\nconst frontendSession = await acpx.sessions.create({\n  agent: 'codex',\n  name: 'frontend'\n});\nconst backendSession = await acpx.sessions.create({\n  agent: 'codex',\n  name: 'backend'\n});\n\nawait frontendSession.prompt('Create React component');\nawait backendSession.prompt('Add API endpoint');\n\n// Fire-and-forget without waiting for completion\nacpx.sessions.send('my-session', {\n  prompt: 'Run tests',\n  noWait: true\n});\n\n// Close session softly\nawait session.close();","lang":"typescript","description":"Demonstrates creating a persistent session, sending prompts, named sessions for parallel work, fire-and-forget mode, and soft-close lifecycle."},"warnings":[{"fix":"Pin exact version in package.json and monitor changelog for breaking changes.","message":"API surface is in alpha and may change significantly between minor versions. Anything built downstream may break until v1.0.0 stabilizes.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Wrap flow definitions with defineFlow().","message":"defineFlow is now required for flow definitions as of v0.5.0. Raw flow objects are no longer accepted.","severity":"breaking","affected_versions":">=0.5.0"},{"fix":"Use the fully qualified agent name or check adapter registry with acpx config.","message":"The `codex` adapter path may change; `codex` is currently an alias and may be renamed in future versions.","severity":"deprecated","affected_versions":">=0.5.0"},{"fix":"Upgrade Node.js to v22.12.0 or higher.","message":"Node.js >=22.12.0 is required. Using older Node versions will result in runtime errors due to ESM features and internal dependencies.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Call session.delete() instead of session.close() to remove persisted history.","message":"Session 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.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Use with caution; follow the runtime embedding API changes in changelog.","message":"The experimental flow runtime (acpx flow run) API is unstable and may change in v0.6.x without notice.","severity":"deprecated","affected_versions":">=0.4.0 <0.6.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Replace 'const acpx = require(\"acpx\")' with 'import acpx from \"acpx\"' in an ESM context, or use dynamic import: `const acpx = await import('acpx')`.","cause":"Using CommonJS require() instead of ESM import.","error":"Cannot find module 'acpx'"},{"fix":"Switch to ESM by adding 'type': 'module' in package.json or use dynamic import.","cause":"acpx is an ESM-only package; CommonJS require is not allowed.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/acpx/... from ... not supported."},{"fix":"Wrap your flow object with `defineFlow(flow)` from 'acpx/runtime'.","cause":"Flow definition not wrapped with `defineFlow` as required since v0.5.0.","error":"TypeError: flow(...) is not a function"},{"fix":"Check available agents with `acpx config show` or provide full path via --agent option.","cause":"Agent name mismatch or missing adapter configuration.","error":"Error: Unknown agent: 'codex'. Available built-in adapters: ..."}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}