Install — acpx

acpx is published to npm as acpx. It is a single Node CLI — no service to host, no daemon to manage. Session state lives under ~/.acpx/.

#Requirements

Node.js 22.12 or newer (see engines.node in package.json)
The underlying coding agent CLI you plan to talk to (Codex, Claude, etc.)

acpx itself does not need a global install of every adapter. Built-in adapters that ship as npm packages (pi-acp, @zed-industries/codex-acp, @agentclientprotocol/claude-agent-acp, @kilocode/cli, opencode-ai) are auto-fetched with npx on first use.

#Global install (recommended)

npm install -g acpx@latest

Verify:

acpx --version
acpx --help

Global install is the default for most workflows because it keeps queue owners and persistent sessions warm between invocations.

#Run without installing

npx acpx@latest codex 'fix the failing tests'

npx works for one-off use but pays a small startup cost on every invocation. For repeated session reuse, prefer the global install.

#Update

npm install -g acpx@latest

Check what changed in the changelog. Pre-1.0 releases can break CLI/runtime surface area between minor versions.

#Where data lives

Path	What it stores
`~/.acpx/sessions/*.json`	Persistent session records (scope key, last prompt, history previews, model, options)
`~/.acpx/queues/<hash>.sock`	Unix socket for active queue owners (named pipe on Windows)
`~/.acpx/queues/<hash>.lock`	Ownership lock file
`~/.acpx/flows/runs/<runId>/`	Persisted flow run bundles (graph state, ACP transcripts, artifacts)
`~/.acpx/config.json`	Optional global config (see Config)
`<cwd>/.acpxrc.json`	Optional project config (merged on top of global, CLI flags still win)

Queue and IPC directories are created with owner-only permissions. acpx re-tightens permissions on previously-permissive directories at startup.

#Build from source

For development or to test an unreleased branch:

git clone https://github.com/openclaw/acpx.git
cd acpx
pnpm install
pnpm run build
node dist/cli.js --help

Run during development without rebuilding:

pnpm dev codex 'fix the tests'

See CONTRIBUTING.md for tests, lint, and the conformance suite.

#Tell your agent about acpx

If you are configuring an upstream coding agent (Pi, OpenClaw, Claude Code) to delegate work through acpx, paste this block into its harness instructions:

I want you to use acpx to run coding agents over the Agent Client Protocol
(ACP) instead of scraping PTY sessions. Please do the following:

1. Install acpx globally (recommended) or use npx:
   npm install -g acpx@latest

2. Install the acpx skill so you have the full reference available:
   npx acpx@latest --skill install acpx

3. Read the acpx skill reference so you know every command, flag, and
   workflow pattern:
   https://raw.githubusercontent.com/openclaw/acpx/main/skills/acpx/SKILL.md

4. Full CLI reference with all options and examples:
   https://acpx.sh/CLI.html

From now on, when you need to delegate work to a coding agent, use acpx
instead of spawning raw terminal sessions.

#Next steps

Quickstart — your first persistent session in two minutes.
Agents — every built-in agent name and what it wraps.
Config — global + project JSON config.