acpx

acpx

このスキルを使う場面

acpx を使ってコーディングエージェントを実行する、永続的な ACP セッションを管理する、プロンプトをキューに追加する、またはスクリプトから構造化出力を利用する必要がある場合に、このスキルを使います。

特に、wave-planner-acpx の承認後に Wave-Driven Development を実行する場合に使ってください。

acpx とは

acpx は、PTY のスクレイピングを行わずにエージェント間の自動化を実現するために設計された、ACP（Agent Client Protocol）用のヘッドレスでスクリプト可能な CLI クライアントです。

主な機能：

• リポジトリ／cwd ごとの永続的な複数ターンセッション
• 1 回限りの実行モード（exec）
• 名前付き並列セッション（-s/--session）
• オプションのファイア・アンド・フォーゲット（--no-wait）に対応したキュー対応のプロンプト送信
• 実行中のターンを協調キャンセル（cancel）
• セッション制御（set-mode、set <key> <value>）
• セッションのメタデータ／履歴の確認（sessions show、sessions history）
• ローカルエージェントプロセスの確認（status）
• 構造化出力形式（text、json、quiet）
• オーケストレーション出力を見やすくする --suppress-reads
• 一時的なプロンプト失敗を再試行する --prompt-retries
• ACP session/set_model による汎用モデル選択
• Codex セッション向けの --model サポート
• v0.4.0 の実験的な flows ランタイムとリプレイ関連ツール

インストール

npm i -g acpx

セッションを安定して再利用するには、npx よりもグローバルインストールを推奨します。

コマンドモデル

prompt がデフォルトです。

acpx [global_options] [prompt_text...]
acpx [global_options] prompt [prompt_options] [prompt_text...]
acpx [global_options] exec [prompt_options] [prompt_text...]
acpx [global_options] cancel [-s <name>]
acpx [global_options] set-mode <mode> [-s <name>]
acpx [global_options] set <key> <value> [-s <name>]
acpx [global_options] status [-s <name>]
acpx [global_options] sessions [list | new [--name <name>] | close [name] | show [name] | history [name] [--limit <count>]]
acpx [global_options] config [show | init]

acpx [global_options] <agent> [prompt_options] [prompt_text...]
acpx [global_options] <agent> exec [prompt_options] [prompt_text...]

組み込みエージェントレジストリ

わかりやすい名前：

• codex -> npx @zed-industries/codex-acp
• claude -> npx @zed-industries/claude-agent-acp
• gemini -> gemini
• opencode -> npx opencode-ai
• pi -> npx pi-acp
• qoder -> qodercli --acp
• trae -> traecli acp serve

ルール：

• デフォルトのエージェントは codex です。
• 未知の位置引数のエージェントトークンは、生のコマンドとして扱われます。
• --agent <command> は、明示的な生のコマンドモードです。
• 位置引数のエージェントトークンと --agent を併用しないでください。

主なワークフロー

永続的なプロンプトセッション

acpx codex 'inspect failing tests and propose fix plan'
acpx codex 'apply minimal fix and run tests'

1 回限りの exec

acpx exec 'summarize this repo'
acpx codex exec 'review changed files'

セッション

acpx sessions new --name backend
acpx codex -s backend 'fix API pagination bug'
acpx codex sessions history backend --limit 20
acpx codex sessions close backend

キューへの追加と no-wait

acpx codex 'run full test suite and investigate failures'
acpx codex --no-wait 'after tests, summarize root causes and next steps'

オーケストレーション向けの構造化出力

acpx --format json codex exec 'review changed files' > events.ndjson

再試行とログの簡略化

acpx codex --prompt-retries 2 'run targeted tests and summarize failures'
acpx --format json --suppress-reads codex exec 'review changed files'

Wave-Driven オーケストレーションのガイダンス

ワーカーエージェントをウェーブ単位で実行する場合：

1. ワーカーごとに名前付きセッションを作成します（-s <agent-name>）。
2. 所有範囲を厳密に定めたプロンプトをワーカーに送信します。
3. 各応答に明示的な完了マーカーを含めるよう求めます。
4. マージする前に、マーカーを確認します。
5. ウェーブの順序に従ってマージします。
6. 次のウェーブに進む前に、統合チェックを実行します。

推奨する完了マーカー： WAVE {WAVE_ID} / {AGENT_NAME} DONE

推奨するワーカー引き継ぎ形式：

1. 概要
2. 変更したファイル
3. パッチ／差分
4. テスト方法（コマンドと期待される結果）
5. リスク／TODO／依存関係に関するメモ

グローバルオプション

• --agent <command> 生の ACP アダプターコマンド
• --cwd <dir> セッションのスコープディレクトリ
• --approve-all すべてのリクエストを自動承認
• --approve-reads 読み取り／検索を承認し、書き込みは確認を求める
• --deny-all すべてのリクエストを拒否
• --model <id> 対象のエージェント／セッションがサポートしている場合にモデルをリクエスト
• --format <fmt> 出力：text、json、quiet
• --suppress-reads ログを見やすくするため、生の読み取り／検索出力を非表示にする
• --prompt-retries <count> 一時的なプロンプト失敗を自動的に再試行
• --timeout <seconds> 最大待機時間
• --ttl <seconds> キュー所有者のアイドル TTL
• --verbose デバッグログ

権限フラグは相互に排他的です。

セッションの動作

永続的なプロンプトセッションは、次の項目をスコープとして扱います：

• agentCommand
• 絶対パスの cwd
• 任意の session 名

ヒント：

• 1 つのリポジトリで並列の作業ストリームを実行する場合は、名前付きセッションを使います。
• --cwd は慎重に使ってください。cwd を変更すると、セッションのスコープも変わります。
• 状態のデバッグには status と sessions show/history を使います。

実用例

並列の名前付きストリーム：

acpx codex -s backend 'implement contract types for Wave 0'
acpx claude -s docs 'draft migration notes for Wave 0'

リポジトリのスコープ内で、許可範囲を広げてレビュー：

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