Related Pages

Related topics: Agent Registry & Built-in Adapters, Session Management, Queues & Lifecycle, Flows, CLI Surface, Permissions & Runtime

acpx Overview & System Architecture

Purpose and Scope

acpx (version 0.11.1, per package.json) is a headless CLI client for the Agent Client Protocol (ACP) that lets AI agents and orchestrators drive coding agents over a structured protocol rather than scraping PTY output. The README frames it as "one command surface for Pi, OpenClaw ACP, Codex, Claude, and other ACP-compatible agents. Built for agent-to-agent communication over the command line." Source: README.md

Its scope covers four concerns:

1. Session lifecycle — persistent, repo-scoped sessions with named parallel workstreams.
2. Prompt transport — queueing, cooperative cancel, fire-and-forget, and crash reconnect.
3. Configuration and policy — global + project JSON config plus permission policies.
4. Multi-step orchestration — TypeScript acpx/flows runtime for multi-step ACP work.

The package distributes three entry points — . (CLI), ./runtime, and ./flows — all built from src/cli.ts, src/runtime.ts, and src/flows.ts for Node 22 ESM. Source: package.json

⚠️ The README explicitly warns: "acpx is in alpha and the CLI/runtime interfaces are likely to change." Source: README.md

High-Level Architecture

flowchart LR
    User[User / Orchestrator] -->|acpx CLI| CLI[src/cli.ts<br/>Command surface]
    CLI -->|resolve| Config[~/.acpx/config.json<br/>+ .acpxrc.json]
    CLI -->|spawn queue owner| Runtime[src/runtime.ts<br/>Session + Queue IPC]
    Runtime -->|ACP stdio| Adapter[Built-in adapter<br/>e.g. codex-acp]
    Adapter -->|wraps| Agent[Underlying CLI<br/>codex / claude / pi / ...]
    CLI -->|flow run| Flows[src/flows.ts<br/>defineFlow runtime]
    Flows -->|acp step| Runtime
    Flows -->|action / compute| Local[Local shell or HTTP]
    Runtime -->|writes| Disk[(~/.acpx/sessions/<br/>~/.acpx/flows/runs/)]

The CLI binary at dist/cli.js is the only user-facing entry point. It parses arguments, resolves configuration (global ~/.acpx/config.json plus project .acpxrc.json), and either spawns a queue-owner process that hosts an ACP child or executes a flow module through the acpx/flows runtime. Source: package.json, src/cli/config.ts

Adapters are auto-downloaded via npx on first use — operators do not install adapter packages manually. Source: README.md

Core Subsystems

Sessions and Queueing

Sessions are persisted under ~/.acpx/sessions/ and identified by a cwd scope plus optional -s <name>. The README documents the lifecycle:

• Prompt queueing: while a prompt is running, new submissions are queued and drained by the running acpx process.
• Queue owner TTL: default 300 s; --ttl <seconds> overrides it; --ttl 0 keeps owners alive indefinitely.
• --no-wait submits to the queue and returns immediately.
• cancel sends cooperative session/cancel over queue IPC; returns nothing to cancel when idle.
• Crash reconnect: a dead pid triggers respawn + session/resume (when advertised) or session/load, falling back to session/new.
• Ctrl+C sends ACP session/cancel and waits briefly for stopReason=cancelled before force-killing.
• exec is always one-shot and never reuses saved sessions.

Source: README.md

Session-control JSON payloads always carry acpxRecordId and acpxSessionId, with agentSessionId present only when the adapter exposes a provider-native id. The text/quiet session id is the local acpx record id — do not assume it can be passed back to the native CLI unless agentSessionId is set. Source: README.md

Configuration

acpx config init writes a ~/.acpx/config.json template; acpx config show prints the resolved global-plus-project config. Per src/cli/config.ts, configuration fields are validated with explicit error messages — for example, ttl must be a non-negative finite number, timeout must be positive, and queueMaxDepth must be a positive integer. The function defaultGlobalConfigPath() resolves to ~/.acpx/config.json and projectConfigPath(cwd) resolves to <cwd>/.acpxrc.json.

Flows Runtime

acpx flow run <file.ts> executes a TypeScript module through the acpx/flows runtime and persists run state under ~/.acpx/flows/runs/. The README identifies five step types:

• acp — keeps model-shaped work in ACP.
• decision() / decisionEdge() — constrained-choice ACP branching without a new node type.
• action — deterministic mechanics like shell or GitHub calls.
• compute — local routing or shaping.
• checkpoint — pauses for something outside the runtime.

Source: README.md, examples/flows/README.md

Shipped examples include echo, branch, shell, workdir, two-turn, the larger pr-triage workflow (which requires an explicit --approve-all grant), and a React Flow-based replay viewer at examples/flows/replay-viewer/. Source: examples/flows/README.md

Built-in Agent Adapters

acpx ships a registry of built-in adapters that map a short CLI name to an ACP-compatible child command. Per agents/README.md, currently documented built-ins include:

Sources: agents/README.md, agents/Codex.md, agents/Trae.md

Unknown names are passed through as raw commands, and --agent '<command>' is the explicit escape hatch for ad-hoc binaries. Source: README.md

Community Notes

A frequently requested addition is an Antigravity (agy --acp stdio) adapter mirroring the existing acpx claude / acpx codex shape (community issue #362). The same pattern — a built-in name pointing at an ACP-spawning child command — is the contract any new adapter must satisfy. Source: README.md

The 0.11.0 release also surfaced cost, token-usage breakdowns, and advertised command metadata on runtime status/events, reflecting ongoing embedding work. The conformance suite at conformance/profiles/acp-core-v1.json defines a draft acp-core-v1 profile (version 0.3.0) covering required cases such as initialize.handshake, session.prompt.multi_turn, permissions.read.approved, and session.cancel.followup_prompt. Source: conformance/profiles/acp-core-v1.json

See Also

• acpx CLI Reference (full option catalog)
• Flows Architecture (docs/2026-03-25-acpx-flows-architecture.md)
• ACP Spec Coverage Roadmap (docs/2026-02-19-acp-coverage-roadmap.md)
• Individual adapter docs under agents/
• PR-triage flow spec at examples/flows/pr-triage/README.md

Related Pages

Related topics: acpx Overview & System Architecture, Flows, CLI Surface, Permissions & Runtime

Agent Registry & Built-in Adapters

Overview

acpx ships as a headless CLI client for the Agent Client Protocol (ACP) and exposes a single, uniform command surface (acpx <agent> ...) for talking to many different coding agents. To keep that surface stable while the underlying agent CLIs diverge, the project maintains a small built-in agent registry: a curated set of short names that resolve to known ACP-compatible commands. The README describes the registry shape as a one-liner per built-in: pi -> npx pi-acp, codex -> npx -y @agentclientprotocol/codex-acp, and so on. Source: README.md:1-120. The canonical inventory is documented in agents/README.md, which lists every built-in and links each one to a per-harness Markdown file. Source: agents/README.md:1-40.

The registry exists for three concrete reasons visible in the source:

1. Ergonomic shorthand. Operators write acpx codex ... instead of acpx npx -y @agentclientprotocol/codex-acp .... Source: README.md:80-120.
2. Onboarding documentation. Each entry has a dedicated agents/<Name>.md describing upstream package, default command, and adapter-specific runtime controls (e.g., ACP modes, advertised models). Source: agents/Codex.md:1-12.
3. Harness-specific capability surfacing. Adapter capabilities like session/set_model, advertised models, or set_config_option are documented per agent so callers know which CLI flag or subcommand to reach for. Source: agents/Codex.md:5-12.

Adapters are auto-downloaded on first use via npx, so users do not need to install adapter packages manually. Source: README.md:60-80.

Built-in Adapter Catalog

The following table summarizes the built-in agents as of acpx v0.11.x. Every row is sourced from agents/README.md and the linked per-harness docs. Source: agents/README.md:1-40, package.json:1-15.

Per-harness notes (upstream URLs, advertised capabilities, model identifiers) are tracked in agents/Codex.md, agents/Claude.md, agents/OpenCode.md, agents/FastAgent.md, and the other sibling files. Source: agents/Codex.md:1-12, agents/README.md:1-40.

Resolution Rules

acpx resolves an agent name through a layered lookup so unknown names still work as raw commands:

1. Built-in lookup. If the leading argument matches one of the registered short names (codex, claude, opencode, etc.), acpx substitutes the corresponding default command and passes through the remaining args. Source: README.md:90-120, agents/README.md:1-40.
2. Raw-command fallback. Any unknown agent name is treated as a literal command prefix. acpx my-agent 'review this patch' becomes my-agent 'review this patch'. Source: README.md:90-120.
3. --agent escape hatch. The global --agent flag lets callers bypass the registry and pin an exact command line, which is the right shape for local dev or CI profiles (e.g., --agent './bin/dev-acp --profile ci' 'run checks'). Source: README.md:90-120.
4. acpx exec and acpx flow run reuse the same registry. Because the registry is consulted before any subcommand, acpx codex exec '...' and acpx codex flow run ./x.flow.ts both resolve the same way. Source: README.md:30-60, src/cli/compare-command.ts:1-40.

The same flags (--cwd, --approve-all, --approve-reads, --deny-all, --timeout, --format, --model, --policy, --non-interactive-permissions) apply uniformly across all registered agents, defined in src/cli/flags.ts. Source: src/cli/flags.ts:1-50, README.md:120-160.

Adding or Extending Adapters

Adding a new built-in is a lightweight, documentation-first change:

• Add the entry to agents/README.md with the form <name> -> <default command>. Source: agents/README.md:1-40.
• Create a sibling agents/<Name>.md describing the upstream package, default command, and any harness-specific runtime controls. Source: agents/Codex.md:1-12.

Recent releases show this pattern working at the registry level: fast-agent -> uvx fast-agent-mcp acp landed in v0.11.0 with the same one-line entry, and the Claude default range was bumped to ^0.37.0 without changing the short name. Source: agents/README.md:1-40, package.json:1-15.

Community requests for new built-ins (for example, issue #362 asking for an antigravity -> agy --acp stdio adapter) follow this exact template: pick a short name, identify a known ACP-stdio entry point, document the default command, and add a per-harness file. Source: [community discussion: #362].

See Also

• README.md — top-level usage and global flags
• agents/README.md — built-in adapter inventory
• agents/Codex.md — Codex capability reference (advertised models, set_model vs set_config_option)
• skills/acpx/SKILL.md — paste-in skill block for delegating to other agents
• examples/flows/README.md — flow authoring examples that compose any registered adapter
• docs/CLI.md — full CLI reference (linked from skills/acpx/SKILL.md)

Related Pages

Related topics: acpx Overview & System Architecture, Flows, CLI Surface, Permissions & Runtime

Session Management, Queues & Lifecycle

acpx is a headless CLI client for the Agent Client Protocol (ACP) that provides persistent, queue-aware session management for coding agents such as Codex, Claude, OpenClaw ACP, Pi, and OpenCode. Sessions survive across invocations, are scoped per working directory, and can be reloaded transparently if the underlying agent process dies. This page documents how sessions are created, addressed, queued, and shut down, drawing on the public CLI surface and flags described in the project README.

Source: README.md

Session Addressing and Scoping

A session is identified by a combination of its working directory and an optional name. The --cwd flag sets the directory scope, and -s <name> (or --session) addresses a named session within that scope, enabling parallel workstreams in the same repo. Source: README.md

Two pointer types are exposed through the CLI:

• cwd-scoped default session: implicit per-directory session used when no name is given.
• named scoped session: addressed by -s <name>, persisted under ~/.acpx/sessions/.

Session selection flags are typed in PromptFlags and SessionsNewFlags and surface as Commander options:

export type PromptFlags = { session?: string; wait?: boolean; file?: string };
export type SessionsNewFlags = { name?: string; resumeSession?: string };

Source: src/cli/flags.ts

The lifecycle of a session includes creation, listing, inspection, history, resumption, closing, pruning, and reloading. The CLI exposes these via the sessions subcommand:

acpx codex sessions new --name api
acpx codex -s api 'implement token pagination'
acpx codex sessions list
acpx codex sessions show
acpx codex sessions history
acpx codex sessions ensure --name api
acpx codex sessions close api

--filter-cwd and --local provide pagination, cwd filtering, and saved-record inspection for sessions list. Source: README.md

Queue Owner, TTL, and Cooperative Cancel

Each session has a long-lived queue owner process that drains prompt submissions sequentially. When a second acpx invocation targets a busy session, the prompt is enqueued to that running owner rather than starting a parallel agent. Idle owners are kept alive for a configurable TTL (default 300 s) so follow-up prompts do not pay cold-start cost.

• --ttl <seconds> overrides the idle TTL; --ttl 0 keeps the owner alive indefinitely.
• --no-wait submits to the queue and returns immediately without waiting for completion.
• cancel performs a cooperative session/cancel via queue-owner IPC; it succeeds with nothing to cancel if no prompt is running.

Source: README.md

The SessionsPruneFlags and SessionsHistoryFlags types in src/cli/flags.ts cover additional lifecycle maintenance:

export type SessionsPruneFlags = {
  dryRun?: boolean;
  before?: Date;
  olderThan?: number;
  includeHistory?: boolean;
};
export type SessionsHistoryFlags = { limit: number };

Source: src/cli/flags.ts

Crash Reconnect and Soft-Close

If a saved session's pid is dead on the next prompt, acpx respawns the agent, attempts session/resume when the adapter advertises it (falling back to session/load), and only falls back to session/new if reconnecting fails. This preserves turn history across crashes. Source: README.md

close performs a soft-close: it ends the live process without deleting history from disk, so the session can be re-opened or audited later. Each successful prompt appends lightweight turn previews (role, timestamp, textPreview) to the session metadata. Source: README.md

Ctrl+C during a running turn sends ACP session/cancel and waits briefly for stopReason=cancelled before force-killing if needed. Source: README.md

Session Runtime Controls and Output Surfacing

The set-mode and set <key> <value> session controls route through queue-owner IPC when active, otherwise they reconnect directly to apply session/set_mode and session/set_config_option. Mode values are adapter-defined; unsupported values are rejected by the adapter, often as Invalid params. Source: README.md

For adapters like Codex that advertise config options, model selection uses the adapter-advertised option:

"acpx --model <id> codex ... and acpx codex set model <id> apply the requested model through the advertised config option; legacy adapters that advertise models use session/set_model."

Source: agents/Codex.md

Runtime status and session events surface token usage breakdowns, cost, and advertised command metadata as part of embedding integration, so operators can inspect session economics from the CLI. Source: README.md

Queue and Lifecycle Flow

flowchart LR
    A[acpx invocation] --> B{Session exists<br/>in ~/.acpx/sessions/?}
    B -- No --> C[Start agent<br/>session/new]
    B -- Yes, alive --> D[Enqueue prompt<br/>via queue IPC]
    B -- Yes, dead --> E[Respawn agent<br/>session/resume or load]
    E -- Fails --> C
    D --> F[Queue owner drains]
    F --> G[ACP session/prompt]
    G --> H[Append turn preview<br/>role, timestamp, textPreview]
    H --> I[Idle TTL countdown<br/>default 300s]
    I -- new prompt --> D
    I -- TTL expires --> J[Soft-close]
    J --> K[History retained on disk]

Source: README.md

The exec subcommand is always one-shot and intentionally bypasses the saved-session lifecycle, which keeps it suitable for stateless automation. Source: README.md

Flows: Multi-Step Lifecycle Beyond a Single Session

For multi-step work, acpx flow run <file> executes a TypeScript flow module through the acpx/flows runtime and persists run state under ~/.acpx/flows/runs/. Flows combine ACP acp steps with deterministic shell-backed action steps (workdir, shell) and decision nodes. Source: examples/flows/README.md

Flows can target an explicit per-step cwd via the acp node so agent work stays inside disposable worktrees. The PR-triage example demonstrates a single persistent main ACP session across a judgment lane:

"If the live ACP connection dies, the runtime should reconnect and try to load the same underlying agent session. If that resume fails, the workflow should fail clearly rather than silently starting a fresh persistent session and pretending context was preserved."

Source: examples/flows/pr-triage/README.md

This composes cleanly with the session lifecycle: a flow can own a named session (-s triage) and rely on acpx's crash-reconnect semantics for that session across the flow's own steps.

Conformance and Output Surface

A draft conformance suite under conformance/ locks down session lifecycle behavior across adapters:

• initialize, session/new, session/prompt, session/update, session/cancel
• Baseline error semantics: Invalid params, permission denied, unknown session

Source: conformance/README.md

Rendered CLI output reflects lifecycle events: assistant text, thought traces, tool calls, plans, and a done marker. Status mapping and tool render state are defined in the formatter, where session notifications are extracted from JSON-RPC messages and tool updates are normalized before display. Source: src/cli/output/output.ts

Common Failure Modes

• Adapter does not advertise resume/load: reconnect falls back to session/new, losing context. The pr-triage spec explicitly requires flows to fail clearly rather than silently restart.
• Unsupported mode/config id: rejected by the adapter, typically as Invalid params.
• TTL expires mid-workflow: a follow-up prompt will cold-start the agent; use --ttl 0 for long-running flows.
• exec is stateless: it never reuses saved sessions and never updates history.

Source: README.md, examples/flows/pr-triage/README.md

See Also

• README.md — full CLI reference and adapter catalog
• examples/flows/README.md — flow authoring surface
• conformance/README.md — protocol-level conformance suite
• agents/Codex.md — adapter-specific session config options

Related Pages

Related topics: acpx Overview & System Architecture, Agent Registry & Built-in Adapters, Session Management, Queues & Lifecycle

Flows, CLI Surface, Permissions & Runtime

acpx is a headless CLI client for the Agent Client Protocol (ACP) that lets AI agents and orchestrators drive coding agents over a structured protocol rather than scraping PTY output (README.md). This page documents four tightly coupled subsystems: the Flows runtime for multi-step TypeScript workflows, the CLI Surface for command and flag handling, the Permissions model for tool approval, and the Runtime that owns session lifecycle, queues, and reconnect.

Project Layout and Tooling

The published package exposes three entry points: acpx (the CLI), acpx/runtime, and acpx/flows (package.json:42-49). The build pipeline is driven by tsdown, targeting Node 22 ESM, with a precommit hook that runs lint-staged and a full rebuild (package.json:50-58). Lint coverage includes oxlint with type-aware rules, oxfmt formatting, a persisted-key-casing check, and a flow-schema-terms check that keeps the public flow vocabulary consistent (package.json:62-66).

CLI Surface

The CLI is a single acpx binary that multiplexes over multiple built-in ACP adapters. Built-in names include codex, claude, pi, openclaw, and a generic escape hatch via --agent '<command>' for unknown harnesses (README.md). Adapter metadata is declared in agents/*.md; for example, the Codex adapter uses npx -y @agentclientprotocol/codex-acp and advertises model ids such as gpt-5.2[high] (agents/Codex.md), while the Trae adapter runs traecli acp serve (agents/Trae.md).

Flag types are defined in src/cli/flags.ts. The relevant option groups are:

Common session subcommands follow a acpx <agent> sessions ... pattern: new, list, show, history, ensure, close, plus status for the local process view (README.md). Prompts can be passed positionally, via --file <path>, or through piped stdin; --no-wait enqueues a prompt and returns immediately, while Ctrl+C sends a cooperative ACP session/cancel before falling back to force-kill (README.md).

Permissions

The permission model offers three explicit modes plus a structured policy override (README.md):

• --approve-all — grant the agent broad tool access
• --approve-reads (default) — allow read-style operations and prompt for writes
• --deny-all — refuse tool use so the agent must answer without external actions
• --permission-policy '<json>' — pass a structured policy such as {"escalate":["execute"],"defaultAction":"deny"} to override defaults without code changes

A separate --non-interactive-permissions fail flag tells acpx to fail rather than deny when there is no TTY available to prompt (README.md). For JSON output, --format json combined with --json-strict enforces machine-safe output; --format quiet is useful for "final recommendation only" runs (README.md).

Runtime and Sessions

The runtime owns persistent, cwd-scoped sessions that survive across CLI invocations, with named sessions enabling parallel workstreams in the same repo (-s backend, -s frontend) (README.md). Lifecycle features include:

• Prompt queueing — additional prompts submitted while a turn is running are queued in order
• Queue owner TTL — --ttl <seconds> keeps the queue owner alive briefly for follow-ups
• Soft-close — sessions close ends the runtime process without deleting on-disk history
• Crash reconnect — dead agent processes are detected and the session is resumed or reloaded
• Session controls — set-mode and set <key> <value> map to session/set_mode and session/set_config_option, with set model routing to the advertised model config option when present (agents/Codex.md)

Flows Runtime

acpx flow run <file> executes a TypeScript flow module through the acpx/flows runtime and persists run state under ~/.acpx/flows/runs/ (README.md). The authoring surface, documented in examples/flows/README.md, exports flows via defineFlow(...) and imports helpers from acpx/flows. Flows compose five node kinds:

flowchart LR
    classDef acp fill:#e3f2fd,stroke:#1565c0,color:#0d47a1;
    classDef control fill:#fff3e0,stroke:#ef6c00,color:#4e342e;
    classDef action fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20;
    ACP["acp step<br/>ACP turn"]:::acp
    DEC["decision / decisionEdge<br/>constrained branch"]:::control
    ACT["action step<br/>shell / GitHub"]:::action
    CMP["compute step<br/>local routing"]:::action
    CHK["checkpoint step<br/>human pause"]:::control
    ACP --> DEC
    DEC -->|continue| ACT
    DEC -->|checkpoint| CHK
    ACT --> CMP
    CMP --> ACP

Flows keep model-shaped reasoning in acp steps, push deterministic mechanics (shell prep, GitHub API calls) into action steps, and use decision() plus decisionEdge() to wrap constrained-choice ACP branching without introducing a new node type (README.md). workdir.flow.ts demonstrates flow workspace isolation — acp nodes can target an explicit per-step cwd, so flows can keep agent work inside disposable worktrees (README.md). The larger pr-triage example intentionally keeps a single persistent main ACP session across its judgment lane so that reconnection after a dropped ACP connection resumes the same agent session; if resume fails, the flow fails clearly rather than silently spawning a fresh session (examples/flows/pr-triage/README.md). The PR-triage flow requires an explicit --approve-all grant and can comment on or close real GitHub PRs when run against a live repository (examples/flows/README.md).

A browser-based replay viewer under examples/flows/replay-viewer/ visualizes saved run bundles with React Flow, a recent-runs picker, and ACP session inspection (examples/flows/README.md).

Community Notes

Issue #362 requests an Antigravity (agy) adapter so that acpx antigravity ... mirrors the existing acpx codex / acpx claude / acpx opencode shape — a pattern consistent with the built-in adapter discovery described above. Release 0.11.0 (per the community context) bumped the default Claude ACP adapter range, surfaced cost, token usage, and advertised command metadata on runtime status/events, and added fast-agent as a built-in ACP adapter, all of which extend the runtime surfaces documented in this page.

See Also

• Quickstart / Installation
• Flow examples index
• PR-triage flow spec
• Codex adapter notes
• CLI flag type definitions

Doramagic Pitfall Log

Found 10 structured pitfall item(s), including 1 high/blocking item(s). Top priority: Security or permission risk - Security or permission risk requires verification.

1. Security or permission risk: Security or permission risk requires verification

• Severity: high
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/openclaw/acpx/issues/406

2. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://www.npmjs.com/package/acpx

3. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://www.npmjs.com/package/acpx

4. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://www.npmjs.com/package/acpx

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://www.npmjs.com/package/acpx

6. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://www.npmjs.com/package/acpx

7. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/openclaw/acpx/issues/385

8. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/openclaw/acpx/issues/387

9. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://www.npmjs.com/package/acpx

10. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://www.npmjs.com/package/acpx

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using acpx with real data or production workflows.

• Persisted token usage is always empty — breakdown rides on the prompt re - github / github_issue
• Session-scoped MCP servers without writing to <cwd>/.acpxrc.json (CLI fl - github / github_issue
• Cursor ACP rejects shared/global --model values in ACPX while other prov - github / github_issue
• acpx 0.11.0 - github / github_release
• 2026.5.23 (v0.10.0) - github / github_release
• 2026.5.22 (v0.9.0) - github / github_release
• 2026.5.15 (v0.8.0) - github / github_release
• acpx 0.6.0 - github / github_release
• acpx 0.5.3 - github / github_release
• acpx 0.5.2 - github / github_release
• acpx 0.5.1 - github / github_release
• acpx 0.5.0 - github / github_release