SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsacpx

acpx

Coding & development

View repository

Updated 10-15 21:36

About this skill

acpx - Headless ACP CLI

A headless CLI client for ACP (Agent Client Protocol), designed for agent-to-agent communication, avoiding PTY scraping issues.

Installation

npm i -g acpx

Core Capabilities

Capability Description
Persistent sessions Multi-turn conversations, automatically resumed by repo/cwd
One-shot execution exec mode, single execution without saving state
Parallel sessions -s/--session named sessions, multiple conversations in the same repository
Queue management Multiple prompts automatically queued,--no-wait async submission
Permission control --approve-all/--approve-reads/--deny-all
Structured output text/json/quiet three formats
Graceful cancellation cancel command or Ctrl+C sends ACP session/cancel

Built-in Agent Registry

Name Command
pi npx pi-acp
qwen qwen --acp
codex npx @zed-industries/codex-acp
claude npx -y @zed-industries/claude-agent-acp
gemini gemini --acp
cursor cursor-agent acp
copilot copilot --acp --stdio
openclaw openclaw acp
droid droid exec --output-format acp
kimi kimi acp
opencode npx -y opencode-ai acp
kiro kiro-cli acp
kilocode npx -y @kilocode/cli acp

The default agent is codex。

Command Model

# 基本用法
acpx <agent> '<prompt>'              # 持久会话模式
acpx <agent> exec '<prompt>'         # 一次性执行
acpx <agent> -s <name> '<prompt>'    # 命名会话

# 会话管理
acpx <agent> sessions                # 列出会话
acpx <agent> sessions new            # 新建会话
acpx <agent> sessions show [name]    # 显示会话详情
acpx <agent> sessions history [name] # 查看历史
acpx <agent> sessions close [name]   # 关闭会话

# 控制
acpx <agent> cancel                  # 取消当前任务
acpx <agent> set-mode <mode>         # 设置模式
acpx <agent> set <key> <value>       # 设置选项
acpx <agent> status                  # 查看状态

Global Options

Option Description
--agent <cmd> Raw ACP agent command (escape hatch)
--cwd <dir> Working directory (affects session scope)
--approve-all Automatically approve all permission requests
--approve-reads Approve reads, writes require confirmation (default)
--deny-all Deny all permission requests
--format <fmt> Output format:text/json/quiet
--timeout <s> Maximum wait time
--ttl <s> Queue owner idle TTL (default 300s)
--verbose Verbose logging

Output Formats

text (default)

Human-readable streaming output, with updates and tool status.

json

NDJSON event stream, suitable for automation:

acpx --format json qwen 'review code' | jq -r 'select(.type=="tool_call") | [.status, .title] | @tsv'

quiet

Output only the final result, suitable for scripting:

result=$(acpx --format quiet qwen exec 'summarize repo')

Practical Workflows

Persistent repository assistant

# 第一次：分析问题
acpx qwen 'inspect failing tests and propose a fix plan'

# 后续：继续同一会话
acpx qwen 'apply the smallest safe fix and run tests'

Parallel named streams

acpx qwen -s backend 'fix API pagination bug'
acpx qwen -s docs 'draft changelog entry for release'

Queue async submission

# 启动任务
acpx qwen 'run full test suite and investigate failures'

# 不等待，排队执行
acpx qwen --no-wait 'after tests, summarize root causes'

One-shot script steps

summary=$(acpx --format quiet exec 'summarize repo purpose in 3 lines')
echo "Summary: $summary"

Machine-readable output for orchestration

acpx --format json qwen 'review current branch changes' > events.ndjson

Using a custom adapter

acpx --agent './bin/custom-acp-server --profile ci' 'run validation checks'

Specify working directory

acpx --cwd ~/repos/myproject --approve-all qwen -s pr-842 \
  'review PR #842 for regressions and propose minimal patch'

Session Behavior

Session scope is determined by:

  • agentCommand(agent command)
  • absolute cwd(working directory)
  • optional session name

Persistence:

  • Session records are stored in ~/.acpx/sessions/*.json
  • -s/--session Create parallel named conversations in the same repository
  • Closed sessions retain closed: true and closedAt timestamps
  • Automatic resume skips closed sessions

Queue Mechanism

Each persistent session has an independent queue:

  • The currently running acpx process becomes the queue owner
  • Other invocations submit prompts via local IPC
  • Unix uses ~/.acpx/queues/<hash>.sock
  • Windows uses named pipes
  • Automatically closes after the owner idle TTL (default 300s)

Configuration Files

Configuration merge order (later takes precedence):

  1. Global:~/.acpx/config.json
  2. Project:<cwd>/.acpxrc.json

Supported configuration:

  • defaultAgent: default agent
  • defaultPermissions: permission mode
  • ttl: idle TTL
  • timeout: timeout
  • format: output format
  • agents: agent name mapping
  • auth: authentication credentials
acpx config show   # 查看配置
acpx config init   # 初始化全局配置模板

Error Handling

  • NO_SESSION: No persistent session, must first sessions new
  • Permission denied: exit when all permission requests are denied
  • Timeout: exceeds --timeout when exiting
  • Ctrl+C: send ACP session/cancel, force terminate after waiting