use-acpx

acpx

重要：バックグラウンド実行が必要です

必ず、すべての acpx bash コマンドで run_in_background: true を使用してください。acpx をフォアグラウンドで実行すると、Claude Code がブロックされ、セッションを使用できなくなります。

acpx コマンドを実行するときは、次のようにします。

{
  "command": "acpx codex 'your prompt here'",
  "run_in_background": true
}

バックグラウンドで実行しないと、エージェントが完了するのを待つ間、Claude Code が無期限にブロックされます。

acpx とは

acpx は、Agent Client Protocol（ACP）用のヘッドレスなスクリプト対応 CLI クライアントです。コマンドライン経由のエージェント間通信向けに構築されており、PTY のスクレイピングを回避します。

警告：acpx で Claude 関連の ACP エージェントを使用しないでください。Claude が Claude を呼び出すと再帰ループが発生し、予測不能な動作につながります。codex、openclaw、gemini などの代替エージェントを使用してください。

主な機能：

• リポジトリ／cwd ごとの永続的なマルチターンセッション
• 1 回限りの実行モード（exec）
• 名前付きの並列セッション（-s/--session、prompt 動詞のみ）
• オプションのファイア・アンド・フォーゲット（--no-wait）に対応した、キューを考慮するプロンプト送信
• 実行中のターンを協調的にキャンセルするコマンド（cancel）
• 割り込み時に ACP の session/cancel を使ったグレースフルなキャンセル
• セッション制御メソッド（set-mode、set <key> <value>）
• サブプロセスの停止検出後のエージェント再接続／再開
• stdin または --file によるプロンプト入力
• グローバル設定とプロジェクト設定をマージする設定ファイル、および config show|init
• セッションのメタデータ／履歴の確認（sessions show、sessions history）
• status によるローカルエージェントプロセスの確認
• ファイルシステムおよびターミナルのリクエストに対応する安定した ACP クライアントメソッド
• 環境変数／設定の認証情報を使った、安定した ACP authenticate ハンドシェイク
• 構造化されたストリーミング出力（text、json、quiet）
• 組み込みのエージェントレジストリと、任意のエージェントを指定できる --agent オプション

インストール

npm i -g acpx

通常のセッション再利用には、npx よりグローバルインストールを推奨します。

コマンドモデル

デフォルトの動詞は prompt です。コマンドの形式は次のとおりです。

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

動詞：prompt（デフォルト）、exec、cancel、set-mode、set、status、sessions、config。プロンプトテキストを省略し、stdin がパイプ接続されている場合、acpx は stdin から読み取ります。文法の詳細については、./references/cli.md を参照してください。

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

重要：Claude 関連の ACP エージェント（例：claude、@zed-industries/claude-agent-acp）は使用しないでください。エージェントがエージェントを再帰的に呼び出す状況が発生し、無限ループや予期しない動作につながる可能性があります。

使いやすいエージェント名は、次のコマンドに解決されます。

• pi -> npx pi-acp
• openclaw -> openclaw acp
• codex -> npx @zed-industries/codex-acp
• gemini -> gemini --acp
• cursor -> cursor-agent acp
• copilot -> copilot --acp --stdio
• 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
• qwen -> qwen --acp

ルール：

• トップレベルの prompt、exec、sessions では、デフォルトのエージェントは codex です。
• 不明な位置引数のエージェントトークンは、任意のエージェントコマンドとして扱われます。
• --agent <command> を使うと、ACP アダプターコマンドを任意に指定できます。
• 同じコマンドで、位置引数のエージェントと --agent を併用しないでください。

コマンド

Prompt（デフォルト、永続セッション）

acpx codex 'fix flaky tests'             # implicit prompt
acpx codex prompt 'fix flaky tests'      # explicit
acpx prompt 'fix flaky tests'            # defaults to codex

スコープ (agentCommand, cwd, name?) に保存されたセッションを自動的に再開します。セッションがない場合は終了コード 4 で終了します。その場合は、先に sessions new を実行してください。キューを考慮するため、プロンプトがすでに処理中の場合は、実行中のキュー所有者に送信します。割り込み時には、強制終了の前に ACP の session/cancel を送信します。

プロンプトのオプション：-s/--session <name>、--no-wait、-f/--file <path>。

Exec（1 回限り）

acpx codex exec 'summarize this repo'

一時セッションで 1 つのプロンプトを実行します。セッション状態は再利用も保存もされません。

注：-s/--session は prompt 動詞専用のオプションで、exec には適用されません。別々の作業ディレクトリ間で並列に 1 回限りの処理を行う方法については、以下の「リポジトリ間／worktree」セクションを参照してください。

Cancel / Mode / Set

acpx codex cancel
acpx codex set-mode auto
acpx codex set approval_policy conservative

cancel は IPC 経由で協調的な session/cancel を送信します。set-mode は ACP の session/set_mode を呼び出します（モード ID はアダプターによって定義されます）。set は ACP の session/set_config_option を呼び出します。どちらも、アクティブな場合はキューオーナー IPC 経由で処理されます。

Sessions

acpx sessions list
acpx sessions new [--name <name>]
acpx sessions close [name]
acpx sessions show [name]
acpx sessions history [name] [--limit <count>]
acpx status

acpx codex sessions new --name backend
acpx codex sessions close backend
acpx codex sessions show backend
acpx codex sessions history backend --limit 20
acpx codex status

主な動作：sessions と sessions list は同じです。new は現在のスコープに新しいセッションを作成します。そのスコープに開いているセッションがすでにある場合は、ソフトクローズされます。show [name] はメタデータを表示し、history [name] はターンのプレビュー（デフォルトは 20 件）を表示します。

ensure、すべてのフラグ、グローバルオプション、設定キー、セッションのスコープ規則、キュー処理の内部動作、出力形式の詳細、権限モード、終了コードを含むサブコマンドの完全な一覧については、./references/cli.md を参照してください。

グローバルオプション（概要）

• --agent <command>：ACP コマンドを直接指定します（エスケープハッチ）
• --cwd <dir>：セッションスコープの作業ディレクトリ
• --approve-all / --approve-reads（デフォルト）/ --deny-all：権限モード（相互排他的）
• --format <fmt>：text（デフォルト）、json、quiet
• --timeout <seconds> / --ttl <seconds>：時間制御（TTL のデフォルトは 300s）
• --verbose：ACP／デバッグログを stderr に出力します

リファレンスの概要

設定ファイル：次の順にマージされます — ~/.acpx/config.json（グローバル）、<cwd>/.acpxrc.json（プロジェクト）。主な設定：defaultAgent、defaultPermissions、ttl、timeout、format、agents マップ、auth マップ。acpx config show を実行すると確認でき、acpx config init を実行するとグローバルテンプレートを作成できます。

セッションの動作：セッションのスコープは agentCommand + 絶対パスの cwd + 任意の name で決まります。記録は ~/.acpx/sessions/*.json に保存されます。プロンプトモードでは Git ルートまで上位ディレクトリをたどって自動再開します。セッションが見つからない場合は終了コード 4 で終了します（sessions new を実行してください）。PID が無効な場合はプロセスを再起動します。並行する会話には -s/--session <name> を使用してください。

プロンプトのキューイング：セッションで最初に起動した acpx プロセスがキューオーナーになり、ほかのプロセスはローカル IPC 経由でリクエストを送信します。デフォルトでは、完了まで待機します。--no-wait を指定すると、キューへの追加後に戻ります。Ctrl+C は強制終了の前に ACP の session/cancel を送信します。オーナーはアイドル状態が TTL（デフォルトは 300s）に達すると終了します。

出力形式：--format text（デフォルト）は人間が読みやすいストリーム、--format json は自動処理用の NDJSON、--format quiet は最終テキストのみを出力します。--json-strict は JSON 以外の stderr 出力を抑制します。

権限モード：次のいずれかを選択します — --approve-all、--approve-reads（デフォルト）、--deny-all。すべてのリクエストが拒否またはキャンセルされ、承認されたリクエストがない場合、acpx は権限拒否ステータスで終了します。

すべてのオプション、サブコマンド、終了コード、IPC の内部動作の詳細については、./references/cli.md を参照してください。

実用的なワークフロー

複数ターンにわたる、リポジトリ用の永続アシスタント：

acpx codex 'inspect failing tests and propose a fix plan'
acpx codex 'apply the smallest safe fix and run tests'

名前付きセッションの並行実行と、キューに追加した後続処理：

acpx codex -s backend 'fix API pagination bug'
acpx codex -s docs 'draft changelog entry for release'
acpx codex --no-wait 'after tests, summarize root causes and next steps'

単発実行と自動化：

acpx --format quiet exec 'summarize repo purpose in 3 lines'
acpx --format json codex 'review current branch changes' > events.ndjson
acpx --cwd ~/repos/shop --approve-all codex -s pr-842 \
  'review PR #842 for regressions and propose minimal patch'

リポジトリ間／ワークツリーへの委任（現在のリポジトリは変更しません）：

# Same shell stays on the orchestration repo; the agent works elsewhere
acpx --cwd /home/dev/code/projectB codex exec 'audit failing CI in projectB'

# Parallel one-shots on isolated worktrees — no --session needed,
# each acpx process is naturally isolated by its --cwd
acpx --cwd /tmp/codex-worktrees/feat-A codex exec 'task A' &
acpx --cwd /tmp/codex-worktrees/feat-B codex exec 'task B' &
wait
# Note: when calling from Claude Code Bash tool, use run_in_background: true
# per-call instead — the &+wait pattern blocks the tool until both complete.

--cwd はエージェントが認識する作業ディレクトリを上書きしますが、スキル、MCP サーバー、設定は引き続きユーザーのホームディレクトリから読み込まれます（codex の場合は ~/.codex/）。初回使用時に信頼確認のプロンプトが表示されないようにするには、対象パスを ~/.codex/config.toml の [projects."<path>"]（Codex 側の TOML 設定）に追加します。

標準入力／ファイルからのプロンプト、セッション管理、JSON 自動化パイプラインなどの例については、./references/cli.md を参照してください。