Changelog

Repo: https://github.com/openclaw/acpx

Unreleased

Changes

• Agents/built-ins: bump the default Claude ACP adapter range to @agentclientprotocol/claude-agent-acp@^0.37.0. Thanks @trumpyla.

Breaking

Fixes

2026.5.23 (v0.10.0)

Changes

• CLI/sessions: add sessions export and sessions import for moving portable session archives between machines. Thanks @mvanhorn.

Breaking

Fixes

2026.5.22 (v0.9.0)

Changes

• Tooling: add Slophammer TypeScript quality gates for coverage, complexity, unsafe types, mutation testing, DRY checks, and dependency boundaries.
• Agents/built-ins: switch the default Codex adapter to @agentclientprotocol/codex-acp, with Codex model selection handled through advertised ACP model ids, and bump the default Claude ACP adapter range.
• Tooling: add a repo-local autoreview skill and helper for Codex-first closeout review with acpx checks in parallel.

Breaking

Fixes

• CLI: treat --version after -- as prompt text instead of intercepting it as a top-level version request.
• CLI: keep custom raw agent commands routed correctly when global flags such as --system-prompt, --append-system-prompt, --prompt-retries, or --no-terminal appear before the agent name. Thanks @amknight.
• CLI/API: avoid installing CLI-only process handlers when the package entrypoint is imported as a module.
• CLI/sessions: use agent-side ACP session/list when available, including cursor pagination, cwd filtering, and agent-native session metadata. Thanks @amknight.
• Sessions/reconnect: use ACP session/resume when adapters advertise it, so resume-only agents can reuse saved sessions without requiring session/load. Thanks @amknight.
• CLI/ACP: validate rich prompt blocks against advertised ACP promptCapabilities and support audio prompt content end-to-end. Thanks @amknight.
• CLI/status: hide stale cached session PIDs when no live helper process exists. Thanks @dutifulbob.

2026.5.15 (v0.8.0)

Changes

• Runtime/embedding: add an optional onPermissionRequest callback to AcpRuntimeOptions and AcpClientOptions so embedders can intercept ACP per-call permission requests with their own UI. Returning a decision short-circuits the mode-based resolver; returning undefined falls through to it, leaving CLI behavior unchanged. Thanks @DaniAkash.
• Runtime/embedding: AcpRuntime.ensureSession now accepts sessionOptions (systemPrompt, model, allowedTools, maxTurns) for fresh sessions, threading the values into _meta.systemPrompt (and _meta.claudeCode.options.*) on the underlying session/new request and persisting them onto the new record. Reusing an existing persistent record continues to ignore sessionOptions since system prompts are fixed at newSession time. SessionAgentOptions and SystemPromptOption are now re-exported from acpx/runtime. Thanks @DaniAkash.
• Runtime/embedding: surface advertised models on AcpRuntimeStatus.models so embedders can build model pickers without reaching into private session records. Thanks @DaniAkash.
• CLI/permissions: add --permission-policy/--policy for per-tool ACP permission rules with autoApprove, autoDeny, escalate, and defaultAction; non-interactive escalations now surface structured tool name/input metadata for orchestrators.

Breaking

Fixes

• Runtime/embedding: preserve structured ACP tool_call_update details on public runtime events, including content, output, locations, kind, and raw payload fields, so embedders can display live tool progress. (#306) Thanks @joeia26.
• CLI/sessions: checkpoint live assistant and tool updates while prompt turns are still running, so sessions read and sessions history can show in-flight progress instead of only the submitted prompt. (#314) Thanks @AndroidPoet.
• Flows: keep external TypeScript flow modules that import acpx/flows compatible with current tsx loader behavior.
• Terminal: run no-argument terminal/create command lines so agents that send an unsplit command do not fail with ENOENT. Thanks @xdjyxu.
• CLI/config: accept command-local --format on config show and config init.
• CLI/sessions: accept the documented -s shorthand on sessions new and sessions ensure.
• Replay viewer: add help output for pnpm viewer --help without starting a server.
• Replay viewer: make pnpm viewer status and pnpm viewer stop dispatch to the requested command instead of always prepending start.
• Package: keep npm pack --json output parseable by running the prepack build quietly.
• CLI/output: exit cleanly on broken pipes so common pipelines such as acpx ... | grep -q ... do not crash with an unhandled EPIPE.
• Tooling: document the current Node.js 22.13+ and pnpm 10.33.2 floor.
• Tooling/docs: document npm-based pnpm bootstrap for clean Node 22.13 setups with stale Corepack signing keys.
• Docs/auth: document the supported authPolicy values and ACP credential selection behavior.
• Docs/skills: make the quick setup skill-install command noninteractive and route unsupported harnesses to the reference URL.
• CLI/queue: honor per-request --prompt-retries when sending a prompt to an already-warm persistent queue owner.
• Runtime/embedding: reject unsupported advertised config option keys before forwarding them to adapters, and map generic thinking controls to advertised effort options when available. (#293)

2026.5.5 (v0.7.0)

Changes

• Flows/authoring: add decision() and decisionEdge() helpers for constrained LLM branching on top of the existing acp, parse, and switch machinery. (#278) Thanks @JoshuaLelon.

Breaking

Fixes

• Runtime/embedding: preserve normalized ACP detailCode values on failed turn results and legacy error events, so embedders can branch on stable error detail codes. (#288) Thanks @kunchenguid.
• Runtime/config: persist advertised configOptions from session/new and session/load and expose their keys through handle-aware runtime capabilities. (#282) Thanks @samithaj.
• CLI/queue: ask active queue owners to send ACP session/close before sessions close terminates their adapter process. (#283) Thanks @codefromthecrypt.
• CLI/models: fail clearly when --model targets a non-Claude ACP agent that does not advertise ACP model support, and reject model ids outside an adapter's advertised availableModels instead of silently falling back to the adapter default.
• Windows/Claude: resolve the claude.exe executable from PATH before spawning Claude ACP sessions, so native Windows launches do not depend on shell-specific command lookup. (#289) Thanks @MikeChongCan.
• Client/ACP: send session/close from closeSession() instead of the experimental nes/close method, so adapters without NES support can tear down sessions cleanly. (#291) Thanks @hexsprite.
• Runtime/WSL: recognize Windows .cmd and .bat ACP agent wrappers for cwd translation, including wrappers installed on non-C drives. (#280) Thanks @solomonneas.

2026.4.25 (v0.6.0)

Changes

• CLI/claude: add --system-prompt <text> and --append-system-prompt <text> global flags that forward through ACP _meta.systemPrompt on session/new, letting callers replace or append to the Claude Code system prompt without dropping out of persistent acpx sessions. The value is persisted in session_options.system_prompt so ensure/reuse flows keep the override. Codex and other agents ignore the field. (#229) Thanks @Vercantez.
• CLI/sessions: add sessions prune with --dry-run, age filters, and --include-history so closed session records and optional event streams can be cleaned up explicitly. (#227) Thanks @coder999999999.
• Runtime/embedding: add startTurn(...) turn handles so embedders can observe live runtime events separately from terminal completion, cancel a turn, or close only the event stream while preserving runTurn(...) compatibility. (#262) Thanks @enki.
• CLI/ACP: add --no-terminal to disable advertised ACP terminal capability for new agent clients. (#155) Thanks @DMQ.
• Agents/built-ins: bump the default @agentclientprotocol/claude-agent-acp, @zed-industries/codex-acp, and pi-acp package ranges so fresh built-in launches pick up the latest adapter releases. (#253, #275) Thanks @flowforgelab.
• Conformance/ACP: add a post-success drain case that catches late tool updates emitted after session/prompt resolves. (#252) Thanks @logofet85-ai.
• Docs/session identity: clarify when CLI output shows ACPX runtime session IDs versus backend agent session IDs.
• Dependencies/CI: update ACP SDK, runtime dependencies, TypeScript-native tooling, formatter/lint tooling, and workflow actions.

Breaking

Fixes

• CLI/runtime: persist non-mode session/set_config_option values and replay them on fresh adapter sessions, so options such as Codex reasoning_effort survive session fallback/reuse. (#138)
• CLI/prompt: honor --model when sending prompts to existing persistent sessions, including queued owner paths. (#211) Thanks @skywills.
• Runtime/persistent sessions: keep reusable persistent ACP clients warm across turns and close pooled clients during runtime close. (#265) Thanks @Sway-Chan.
• Runtime/ACP: drain late post-success session updates before closing prompt turns so adapters that resolve session/prompt before final updates do not drop assistant output. (#251) Thanks @logofet85-ai.
• Runtime/embedding: reuse the saved persistent session when sending runtime controls instead of creating a new backend session for control operations.
• CLI/sessions: persist the submitted prompt at turn start so sessions history and sessions read no longer report No history while an active prompt is already running. (#157)
• Runtime/WSL: translate session cwd with wslpath when running under WSL and spawning Windows .exe ACP agents, so session/new and session/load receive paths the agent can access. (#232)
• Client/auth: require explicit ACPX_AUTH_* env vars or config auth entries for ACP auth-method selection, so ambient provider env like OPENAI_API_KEY no longer triggers unintended login flows in adapters such as codex-acp.
• Config/agents: honor custom agent args arrays from config instead of silently dropping required adapter subcommands. (#199) Thanks @log-li.
• CLI/queue: tighten persistent queue and IPC socket directories to owner-only permissions, including previously-created permissive directories. (#216) Thanks @garagon.
• CLI/queue: use cryptographically random owner generation IDs so rapid queue owner restarts cannot reuse a stale generation token. (#207) Thanks @Yuan-ManX.
• Output/errors: add text-mode remediation hints for auth-required, missing-session, ACP session failures, timeouts, provider rate limits, and invalid model names while keeping JSON error payloads stable. (#256) Thanks @SJeffZhang.
• CLI/quiet output: emit final token usage and cost metadata to stderr when adapters include it in the ACP prompt result, while keeping quiet stdout as assistant text only. (#257)
• CLI/status: report resumable persistent sessions as idle when no queue owner is running, instead of marking pre-prompt or TTL-expired sessions as dead. (#185)
• Client/ACP: use the locked ACP SDK close API path so session closing stays compatible with the current SDK.
• Runtime/doctor: guarantee doctor().details contains strings even when probe failures include Error or object values. (#267)
• Replay viewer: protect run-bundle file reads from run-id boundary escapes.

2026.4.8 (v0.5.3)

Changes

• Dependencies: upgrade Vite to 8.0.7. (#231) Thanks @hxy91819.

Breaking

Fixes

2026.4.7 (v0.5.2)

Changes

Breaking

Fixes

• Sessions/reset: close the live backend session when discarding persistent state so reset flows start a fresh ACP session instead of silently reopening the old one. (#228) Thanks @dutifulbob.

2026.4.6 (v0.5.1)

Changes

Breaking

Fixes

• Runtime/processes: own built-in adapter launches so child processes are managed consistently. (#226) Thanks @dutifulbob.

2026.4.6 (v0.5.0)

Changes

• Flows: validate flow definitions and require defineFlow. (#219) Thanks @osolmaz.
• Runtime/embedding: add a supported acpx/runtime API for embedding ACPX session lifecycle, turn execution, status/control, and file-backed runtime storage. (#220) Thanks @osolmaz.
• Runtime/prompt turns: stabilize runtime prompt turn handling. (#222) Thanks @osolmaz.

Breaking

Fixes

2026.4.4 (v0.4.1)

Changes

• Flows/replay viewer: keep recent runs and the active recent-run view live over a WebSocket snapshot/patch transport so in-progress runs update without manual refresh while rewind stays available. (#205) Thanks @osolmaz.
• Agents/built-ins: bump the default pinned @zed-industries/codex-acp and @agentclientprotocol/claude-agent-acp package ranges. (#215) Thanks @osolmaz.
• Dependencies: update ACP SDK, TypeScript, and TypeScript-native dev tooling. (#200, #202, #203)

Breaking

Fixes

2026.3.29 (v0.4.0)

Changes

• Flows/workflows: add an initial flow run command, an acpx/flows runtime surface, and file-backed flow run state under ~/.acpx/flows/runs for user-authored workflow modules. (#179) Thanks @osolmaz.
• Flows/replay: store flow runs as trace bundles with manifest.json, flow.json, trace.ndjson, projections, bundled session replay data, and per-attempt ACP/action receipts for later inspection. (#181) Thanks @osolmaz.
• Flows/replay viewer: add a React Flow-based replay viewer example that replays saved run bundles and shows the bundled ACP session beside the graph. (#183) Thanks @osolmaz.
• Flows/permissions: let flows declare explicit required permission modes, fail fast when a flow requires an explicit --approve-all grant, and preserve the granted mode through persistent ACP queue-owner paths. (#186) Thanks @osolmaz.
• Flows/workspaces: let ACP validation choose PR test plans and broaden PR-triage refactor judgment. (#189, #190) Thanks @osolmaz.
• Flows/titles: add a flow run title API. (#197) Thanks @osolmaz.
• Agents/trae: add built-in Trae agent support backed by trae-cli. (#171) Thanks @hqwuzhaoyi.
• Agents/qoder: add built-in Qoder CLI ACP support via qoder -> qodercli --acp and document Qoder-specific auth notes. (#178) Thanks @xinyuan0801.
• Agents/codex: support --model for Codex sessions. (#192) Thanks @osolmaz.
• Models: add generic model selection via ACP session/set_model. (#150) Thanks @ironerumi.
• Output: add --suppress-reads to mask raw file-read bodies in text and JSON output while keeping normal tool activity visible. (#193) Thanks @osolmaz.
• CLI/prompts: add --prompt-retries to retry transient prompt failures with exponential backoff while preserving strict JSON behavior and avoiding replay after prompt side effects. (#196) Thanks @osolmaz.
• Docs/PR triage: add conflict gates and standard check validation guidance for maintenance PRs. (#180, #187) Thanks @osolmaz.
• Dependencies: update ACP SDK, workflow actions, TypeScript-native tooling, and development dependencies. (#131, #133, #146, #154, #177)

Breaking

Fixes

• Sessions/load: fall back to a fresh ACP session when adapters reject session/load with JSON-RPC -32601 or -32602, so persistent session reconnects do not crash on partial load support. (#174) Thanks @Bortlesboat.
• Flows/runtime: finalize interrupted flow run bundles as failed instead of leaving them stuck at running when the process receives SIGHUP, SIGINT, or SIGTERM. (#188) Thanks @osolmaz.
• Windows/process spawning: enable shell mode for terminal spawn on Windows. (#173) Thanks @Bortlesboat.
• Client/startup: add connection timeout and max buffer size limits. (#168) Thanks @Yuan-ManX.
• Client/auth: cache derived auth env key lists per auth method to avoid repeated allocations during credential lookup. (#167) Thanks @Yuan-ManX.
• Output/thinking: preserve line breaks in text-mode [thinking] output instead of flattening multi-line thought chunks into one line. (#194) Thanks @osolmaz.
• Agents/cursor: recognize Cursor's Session "..." not found session/load error format so reconnects fall back to session/new instead of failing. (#195) Thanks @osolmaz.
• Agents/kiro: use kiro-cli-chat acp for the built-in Kiro adapter command to avoid orphan child processes. (#129) Thanks @vokako.

2026.3.18 (v0.3.1)

Changes

• Conformance/ACP: add a data-driven ACP core v1 conformance suite with CI smoke coverage, nightly coverage, and a hardened runner that reports startup failures cleanly and scopes filesystem checks to the session cwd. (#130) Thanks @lynnzc.
• Agents/droid: add factory-droid and factorydroid aliases for the built-in Factory Droid adapter and sync the built-in docs. (#156) Thanks @vincentkoc.

Breaking

Fixes

2026.3.12 (v0.3.0)

Changes

• Agents/built-ins: add Factory Droid and iFlow as built-in ACP agents and document their built-in commands. (#112, #109) Thanks @ironerumi and @gandli.
• Dependencies: update TypeScript-native and tsdown development tooling. (#106, #107, #118, #125, #126)

Breaking

Fixes

• Codex/session config: treat thought_level as a compatibility alias for codex-acp reasoning_effort so acpx codex set thought_level <value> works on current codex-acp releases. (#127) Thanks @vincentkoc.
• Session control/errors: surface actionable set-mode and set error messages when adapters reject unsupported session control params, and preserve wrapped adapter metadata in those failures. (#123) Thanks @manthan787.
• Sessions/load fallback: suppress recoverable session/load error payloads during first-run prompt recovery and keep the session record rotated to the fresh ACP session. (#122) Thanks @lynnzc.
• Permissions/stats: track client permission denials in permission stats. (#120) Thanks @lynnzc.
• Agents/gemini: default to --acp for Gemini CLI and fall back to --experimental-acp for pre-0.33 releases. (#113) Thanks @imWildCat.
• Images/prompt validation: validate structured image prompt block MIME types and base64 payloads, emit human-readable CLI usage errors, and add an explicit non-CI live Cursor ACP smoke test path. (#110) Thanks @vincentkoc.
• Windows/process spawning: detect PATH-resolved batch wrappers such as npx on Windows and enable shell mode only for those commands. (#102) Thanks @lynnzc.

2026.3.10 (v0.2.0)

Changes

• Docs/changelog: add missing changelog entries, align the changelog with OpenClaw style, and clean up duplicate ACP and queue helpers. (#104, #105, #108) Thanks @vincentkoc.

Breaking

Fixes

• ACP/prompt blocks: preserve structured ACP prompt blocks instead of flattening them during prompt handling to support images and non-text. (#103) Thanks @vincentkoc.

2026.3.10 (v0.1.16)

Changes

• Tooling: align acpx tooling with the wider OpenClaw stack. (#43) Thanks @dutifulbob.
• Docs/contributors: sync contributor guidance with OpenClaw, add the vision doc, and refocus the agent contributor guide. (#68, #97) Thanks @onutc.
• ACP/set-mode: clarify that set-mode mode IDs are adapter-defined. (#27) Thanks @z-x-yang.
• Tests/coverage: expand CLI, adapter, and session-runtime coverage and keep the coverage lane on Node 22. (#69, #89) Thanks @vincentkoc and @frankekn.
• Agents/built-ins: add built-in agent support for Copilot, Cursor, Kimi CLI, Kiro CLI, kilocode, and qwen. (#72, #98, #56, #40, #62, #53) Thanks @vincentkoc, @osolmaz, @gandli, @vokako, and @kimptoc.
• Sessions/read: add a sessions read command. (#88) Thanks @frankekn.
• Config/exec: add a disableExec config option. (#91) Thanks @gandli.
• Claude/session options: add CLI passthrough flags for Claude session options. (#94) Thanks @frankekn.
• Sessions/resume: add --resume-session to attach to an existing agent session. (#95) Thanks @frankekn.
• ACP/config: pass mcpServers through ACP session setup. (#96) Thanks @frankekn.
• Docs/registry: sync the agent registry documentation with the live built-in registry. (#55) Thanks @gandli.
• Runtime/perf: improve runtime performance and queue coordination, tighten perf capture, reuse warm queue-owner ACP clients, and lazy-load CLI startup modules. (#73, #84, #87, #86) Thanks @vincentkoc.
• Repo/maintenance: add Dependabot configuration and pin ACP adapter package ranges. (#74, #99) Thanks @vincentkoc and @osolmaz.
• Docs/alpha: refresh code and adapter alpha docs. (#75) Thanks @vincentkoc.
• Dependencies: batch pending dependency upgrades. (#83) Thanks @vincentkoc.

Breaking

Fixes

• Queue/runtime: stabilize queue sockets and related runtime coordination paths. (#73) Thanks @vincentkoc.
• Gemini/ACP startup: harden Gemini ACP startup and reconnect handling, then fix follow-on session reconnect regressions. (#70, #93) Thanks @vincentkoc and @Takhoffman.
• Claude/ACP startup: harden Claude ACP session creation stalls. (#71) Thanks @vincentkoc.
• Windows/process spawning: use cross-spawn for Windows compatibility. (#57) Thanks @sawyer0x110.
• Release/CI: restore the CI release bump flow and keep release jobs on GitHub-hosted runners. (#100, #101) Thanks @osolmaz.

2026.3.1 (v0.1.15)

Changes

Breaking

Fixes

• CLI/version: restore --version behavior and staged adapter shutdown fallback. (#41) Thanks @dutifulbob.

2026.3.1 (v0.1.14)

Changes

• ACP/session model: land the ACP session model work and define the ACP-only JSON stream contract. (#28, #34) Thanks @osolmaz and @dutifulbob.
• Queue/owner: make the queue owner self-spawn through the acpx CLI entrypoint. (#36) Thanks @dutifulbob.
• Metadata/release: restore OpenClaw package metadata for trusted publishing. (#39) Thanks @dutifulbob.
• Tests/queue owner: stabilize queue-owner integration teardown with additional tests. (#37) Thanks @dutifulbob.

Breaking

Fixes

• Gemini/session restore: recognize Gemini CLI Invalid session identifier failures as session-not-found reconnect cases. (#35) Thanks @louria.
• Sessions/output: suppress replayed loadSession updates from user-facing output. (#38) Thanks @dutifulbob.

2026.2.26 (v0.1.13)

Changes

Breaking

Fixes

• CLI/version env: ignore foreign npm_package_version values in npx contexts when resolving the CLI version. (#25) Thanks @dutifulbob.

2026.2.26 (v0.1.12)

Changes

• CLI/version: add dynamic --version resolution at runtime. (#24) Thanks @dutifulbob.

Breaking

Fixes

2026.2.25 (v0.1.11)

Changes

• Runtime/owners: detach warm session owners from prompt callers and run the opencode adapter in ACP mode. (#23) Thanks @dutifulbob.

Breaking

Fixes

2026.2.25 (v0.1.10)

Changes

Breaking

Fixes

• ACP/reconnect: fall back cleanly when a persisted ACP session is no longer found. (#22) Thanks @dutifulbob.

2026.2.25 (v0.1.9)

Changes

• Docs/session identity: clarify the ACP session identity model and current coverage status. (#21) Thanks @dutifulbob.

Breaking

Fixes

2026.2.24 (v0.1.8)

Changes

• Docs/runtime: specify runtime session id passthrough from ACP metadata. (#18) Thanks @dutifulbob.
• Metadata/repo: update repository metadata for openclaw/acpx. (#19) Thanks @osolmaz.

Breaking

Fixes

2026.2.23 (v0.1.7)

Changes

• Docs/install: restore global install instructions, badges, and skillflag guidance. (#14) Thanks @dutifulbob.
• Runtime/OpenClaw: add OpenClaw ACP integration runtime and CLI primitives. (#17) Thanks @dutifulbob.

Breaking

Fixes

2026.2.20 (v0.1.6)

Changes

• Docs/readme: add banner, badges, skillflag 0.1.4 guidance, and simplified setup. (#12, #13) Thanks @dutifulbob.

Breaking

Fixes

2026.2.20 (v0.1.5)

Changes

• Docs/install: clarify npx usage and use @latest in install commands. (#5, #6) Thanks @dutifulbob.
• Runtime/session UX: implement high-priority runtime, config, and session UX features. (#7) Thanks @dutifulbob.
• Tests/integration: add mock ACP agent and integration tests. (#9) Thanks @dutifulbob.

Breaking

Fixes

• Startup/cancel: cancel prompts during startup correctly. (#10) Thanks @dutifulbob.

2026.2.18 (v0.1.4)

Changes

• Docs/setup: add quick-setup guidance for agent skill install. (#3) Thanks @dutifulbob.
• Sessions/prompts: require explicit sessions and route prompts by directory walk. (#4) Thanks @dutifulbob.

Breaking

Fixes

2026.2.18 (v0.1.3)

Changes

• CI/tests: align CI and test setup with SimpleDoc and expand coverage. (#1) Thanks @dutifulbob.

Breaking

Fixes

• Release: align release workflow with the skillflag in-memory bump pattern. (#2) Thanks @dutifulbob.

2026.2.18 (v0.1.2)

Changes

• Initial public release of the ACP CLI client, including npm-first docs, agent-first prompt/exec/session commands, async prompt queueing, the initial agent registry, CI, trusted publishing, and MIT licensing.

Breaking

Fixes