tmux-agent-tools

Tmux エージェントツール

すぐ使える方法（最初にお読みください）

絶対に守るルール：

1. エンジン専用 — ワーカーに生の tmux を決して入力しないでください。 すべてのワーカーは agent-tmux <cli> サブコマンド（send-wait、status、result、capture、stop）を使って操作します。読み取り専用の一覧確認には tmux-agent-sessions list を使い、生の tmux ls は使わないでください。生の tmux では、命名規則、機密情報のマスキング、結果の契約、クリーンアップを回避してしまいます。エンジンにコマンドがないと判断する前に、下記の機能一覧を確認してください。通常のシェルは、本当に機能が不足している場合の最後の手段です。その場合は理由を説明してください。
2. 送信が確認できるまでは、send は完了ではありません。 単独の send では、入力ボックスにテキストが残り、送信されないことがあります。デフォルトでは send-wait を使ってください。新しい nonce を追加して待機し、プロンプトが届いたことを確認できます。
3. ブロッキング待機には必ずタイムアウトを指定してください。sleep やポーリングのループを自作してはいけません。 複数のワーカーには、1つの上限付き watch --any|--all|--count <n> --timeout <s> --json … を使ってください。複数エンジンが混在する場合は、reason:result_updated を信頼するか、tmux-agent-sessions で解決してください。
4. ワーカーを再利用して追加タスクを実行しますか？ まず result init、次に send-wait、最後に result wait-required を実行してください。result init なしで再利用すると、待機時に前回の古い結果が返されます。詳細は references/multi-agent.md#persistent-teammates-worker-reuse を参照してください。

すぐ使える回答：

• 後続作業のない、範囲が限定されたタスクですか？ デフォルトでは、対話型の start（画面あり）を使います。tmux ペインがデバッグ画面です。capture、status、または接続すれば、CLI が実行中および実行後に何をしているかを正確に確認できます。start --headless（claude -p / codex exec）はオプトインのみです。ユーザーから明示的に求められた場合、または出力を簡単に検証でき、実行内容を確認する必要がない場合に限ります。ヘッドレスで失敗した場合、残るのは終了コードと stdout ファイルだけです。これが何度も確認されており、手がかりのないデバッグに長時間を費やすことになります（ユーザーの裁定、2026-08-03：デフォルトは画面あり）。
• ラッパーが PATH にありませんか？ このバンドルから実行します：<skill-dir>/scripts/agent-tmux codex …。
• ワーカーが「失敗」したのに、ペインには PASS と表示されていますか？ 終了コードは判定結果ではありません。再ディスパッチや失敗の報告をする前に、references/core-workflow.md#5-read-the-agents-structured-result（「終了コードは判定結果ではない」）を確認してください。
• 相当量の作業を自動委任しますか？ using-tmux-agent-tools スキルのインライン実行とワーカー実行の判定ゲートを使います（そこで統合済みであり、独立したサブエージェントではなくなっています）。詳細は references/core-workflow.md にあります。
• 長時間実行される外部 CLI ワーカー（Codex または Claude Code）ですか？ agent-tmux <cli> assign <name> <dir> <prompt-file> の呼び出しを1回だけ使ってディスパッチします。段階的な手順（start → result init → send → confirm-processing → blocking supervise）がそのまま監督にあたるため、プロキシはその手順を実行し、それ以外は行いません（以前のワーカーごとの polling プロキシは廃止済みです。2026-08-08）。ホストは監督プロキシを1つだけ使用します。プロキシのブリーフで単一の assign 呼び出しを実行し、その終了コードを報告する sonnet low の general-purpose サブエージェントです（model-dispatch.md §4、2026-08-17/18 の裁定を参照）。親プロセスのフォアグラウンド assign は、--detach を含め、いかなる形式でも禁止されており、tmux-assign-host-gate フックによってツール呼び出し時に拒否されます。プロキシが非終端状態を報告した場合、親プロセスでの run_in_background は必須であり、最後の手段ではありません。2026-08-30 の計測によると、ハーネスは約600秒でプロキシのフォアグラウンド呼び出しを終了させ、サブエージェントには TaskOutput がありません。そのため、終了させられたプロキシが報告できるのは実行中の状態だけであり、親プロセス自身が待機を担う必要があります（終了したサブエージェントが残したタスクは誰にも通知されません。インシデント c48c0d3a では、このために2時間40分が失われました）。理由を実行ディレクトリに記録し、リスナーをパイプに通さないでください。末尾の | tail は tail のステータスを返すため、ラッパーの exit 2 が成功として扱われます。親プロセスは、assign がステップの失敗を報告した場合、またはユーザーから求められた場合を除き、追加で status／capture／probe をポーリングしてはなりません。result wait-required --wait <s> を、上限を設けて呼び出し、結果を取得します。pending は判定結果ではなく、処理を終えるための手順です。上限の範囲内で待ち続け、上限に達しても pending の場合は、result --path <name> から取得した文字列どおりのパスを示してワーカーに1回だけ再プロンプトし、上限を設けてもう1ラウンド待ちます。その後に限り、ペインのキャプチャを代用として使用できますが、未確認と明記し、検証済みの回答として提示してはなりません。assign の result-path delivery UNCONFIRMED 警告に従ってください。パスを知らされていないワーカーは result.json を書き込めないため、その pending は永久に解消されません。終了時の順序：監督対象のワーカーを停止する前に、プロキシを先に停止してください。そうしないと、プロキシは届かなくなったシグナルを待ったまま取り残されます。ワーカーの出力をそのまま返すようプロキシに指示してはなりません。その出力を読むことは禁止されているため、そのブリーフは実行不可能です。ワーカーには宣言済みの成果物パスに書き込ませ、自分でそのファイルを読み取ってください。
• ワーカーのプロンプトを書いていますか？ delegation-templates スキルを使って構成します。GOAL / ACCEPTANCE / REPORT と共通フッターに、tmux 用の追記（カスケード委任の禁止 + 文字列どおりの結果パス）を加えます。
• 新しい CLI、または名前を変更した CLI ですか？ bin=… を含むプロファイルを追加し、doctor --json と start --dry-run で動作を確認します。references/profiles.md を参照してください。

概要

agent-tmux <cli> <command> は、任意の AI コーディング CLI を管理対象の tmux ワーカーとして実行します。claude／codex／agy は組み込みプリセットで、その他の CLI では任意のプロファイルを使用します。CLI ごとのバイナリはありません。常に agent-tmux <cli> <command> の形式で指定してください。

必須の事前確認と安全な呼び出し

最初のワーカーコマンドを実行する前に：

1. PATH を前提にせず、ラッパーバンドルを解決します。次の順に確認します。 <repo-dir>/skills/tmux-agent-tools/scripts、 ~/.agents/skills/tmux-agent-tools/scripts、 ~/.claude/skills/tmux-agent-tools/scripts、 ~/.codex/skills/tmux-agent-tools/scripts。バンドルが存在せず、PATH の検索が成功した場合に限り、ラッパー名をそのまま使用します。
2. 解決した agent-tmux <cli> setup を実行し、事前確認に失敗した場合は中止します。
3. タスクの生テキストは、個別に引用符で囲んだ引数またはプロンプトファイルの内容として渡します。タスクのテキストを eval、sh -c、構築したシェルコマンドに埋め込んではいけません。
4. タスク固有の認証情報は、--secret KEY=URI のみで渡します。認証情報の値をタスクのテキストや構築したシェルコマンドに埋め込んではいけません。

使用する場面

• 後から監督する必要がある、長時間実行の Claude／Codex／agy／カスタム CLI 作業。
• 親エージェントまたはラッパー向けに、ワーカーが構造化された result.json を書き出す必要がある場合。
• 検証済みの後続送信、稼働状況／ステータス確認、上限付き待機、クリーンアップが必要な場合。
• 複数のワーカーについて、1 回のラッパー watch 呼び出しで最初／すべて／N 件の完了を待つ場合。

コマンドの選択

必要なこと	使用するもの
Claude Code／Codex／agy をワーカーとして実行する	agent-tmux claude／agent-tmux codex／agent-tmux agy
その他の CLI（gemini、cursor、grok、カスタム）	agent-tmux <cli>（＋任意のプロファイル）
すべてのワーカー（上限付きの単発実行を含む）	対話型の start（ヘッド付き）。ペインがデバッグ用の画面になります。デフォルト。
機械的に検証できる実行して回収するだけの処理で、ユーザーが選択している場合	start --headless。完了はプロセスの終了で判定され、失敗時に残るのは終了コードと標準出力ファイルのみです。
ローカルの作業ディレクトリ	start
別のホスト上のリポジトリ（tmux はローカルに維持）	start-ssh
1 回の実行でモデルを固定する	start --model <m> <name> <dir> '<prompt>'
既存の CLI セッション UUID を続行する	resume（オプトイン。デフォルトでは無効）
セッションを管理しているラッパーがわからない	最初に tmux-agent-sessions resolve --name <n> --json を実行
2 者間のやり取り／1 対多の作業	tmux-agent-dialogue／tmux-agent-fanout
読み取り専用の一覧表示または証拠のポーリング	tmux-agent-sessions／tmux-agent-monitor

start のフラグは位置引数より前に指定します：start --exact --model <m> <name> <dir>。フラグの位置が誤っている場合は 2 で終了します。

すべてのサブコマンドと使用場面を網羅した機能一覧表：references/cheatsheets.md。

使用しない場面

• 単発のシェルコマンド、または単純なファイルの読み取り、検索、テスト、ビルドの場合。ワーカーを起動せず、直接実行します。
• ユーザーから事前に許可を得ていない、外部に影響する作業、破壊的な作業、またはプライバシーに関わる作業。

よく使う 6 つのコマンド

# Dispatch a prompt-file task: ONE command runs the whole verified sequence
# (start -> result init -> send --from-file -> confirm the pane is processing
# -> blocking supervise). Prefer this over hand-chaining the steps; it cannot
# be misordered and it catches "task never reached the CLI" before waiting.
agent-tmux codex assign job ~/repo /abs/path/prompt.txt

# Bounded one-shot (headed by default; add --headless only when the user opted in):
agent-tmux codex start --exact job ~/repo 'Task. Write final JSON to the wrapper-provided result path when done.'
agent-tmux codex result wait-required job --fields status,summary --wait 600 --json   # returns at process exit
agent-tmux codex supervise --result-required --silent-while-unchanged --json job       # one silent call until terminal event
agent-tmux codex stop job

# Interactive one-worker flow (only when follow-ups are needed): start -> send-wait -> supervise -> stop.
agent-tmux codex start --exact worker ~/repo 'Task. Write final JSON to the wrapper-provided result path when done.'
agent-tmux codex send-wait worker 'Follow-up instruction.' 180
agent-tmux codex status --json worker
agent-tmux codex result --json --wait 30 worker
agent-tmux codex stop worker

# Multiple workers: block on first/all/N completion with one bounded call.
agent-tmux codex watch --any --timeout 600 --json w1 w2 w3

一連の操作を詳しく説明したガイド：references/core-workflow.md。

v5 台帳（Claude 以外のホスト）

Codex、Cursor、agy は Claude の関数フックモジュールを読み込みません。同じ v5 台帳、つまり状態ルートの .v3/ ツリーを使用します。このバンドルの Node エントリーポイントは scripts/lib/collector.node.ts（ホストセッションごとに 1 つのコレクター）と scripts/lib/workers.cli.node.ts（cancel、unlock）です。ワーカーの TUI は scripts/tmux-agent-tui [--session <id>] [--cwd <dir>] です。セッション ID を指定すると、そのセッションのワーカーを管理するオーナーとして動作します。指定しない場合は読み取り専用のビューアーとして動作します。Node >= 22.18 と TTY が必要です（それ以外は終了コード 2。--help にはどちらも不要です）。スキルを更新した後は、scripts/install-bin を再実行してください。このスクリプトは、最後に実行した時点で存在したスクリプトのみをリンクします。リンクが不足している場合は agent-tmux <cli> doctor に表示されます。レイアウト、所有権、配信方法については、リポジトリのドキュメント mods/tmux-agent/README.md（収集端）を参照してください。このスキルではそのレイアウトを再掲しません。Bash ガード（tool.call）は Claude 専用です。同じ tailnet 上のホスト間では、scripts/tmux-agent-relay（ensure、send <host> <worker> <text>、roster）と start-ssh --sentinel … --notify を使用します（リモートの終了情報は status --json の exit_source: "relay" に反映されます）。信頼モデルと拒否条件については、README の「Relay (tailnet)」セクションを参照してください。

result.json の完了契約

エージェントは $TMUX_AGENT_DIR/<name>/result.json に、schema_version: 1、正規の status（success|failed|blocked|needs-input）、summary、artifacts、errors（任意の verdict／decision、および、成功時にコミットを作成した場合は完全な40桁の16進数の sha である commit）を記述します。tmux-agent mod は、そのコミットがディスパッチ時のベース（エピソード開始時の HEAD）から派生したコミットであることを確認し、commit <sha12> verified (…) または success claimed, commit <sha> NOT verified: <reason> を返します。コミットを作成しなかった場合は省略してください。セッションで最初にプロンプトを送信すると、リテラルの結果パスが（デフォルトではすべてのファミリーに）挿入されます。ワーカーはツールのサンドボックス内で $TMUX_AGENT_RESULT を利用できるとは限りません。分岐はこの順序で行ってください。有効な結果がある場合は、ペインの内容を決してスクレイピングしないでください。.present -> .valid -> .body の順です。

--fields には、この契約のキーを指定します。プロンプトのプレースホルダーではありません。どのワーカーも書き出さない artifact_path を指定して収集したため、2026-09-08 に完了済みのワーカー2つが約24分間、収集されないままになりました。status,summary を指定して .body を読み取り、生成ファイルは .body.artifacts として要求してください。要求されたフィールドが欠けているターミナル結果は、待機せずに 3 で終了するようになりました（event:"contract-mismatch"、ワーカーの body を添付）。フィールド一覧を修正し、再ディスパッチはしないでください。CLI を起動できない場合は、assign のステップ0で blocked_reason（keychain_locked、login_required、quota_exhausted、cli_not_found）を伴って 4 で終了し、何も開始しません。ブロッカーを報告し、待機はしないでください。改行のたびに送信する TUI では、assign --prompt-delivery file-ref（プロファイル prompt_delivery。agy に同梱）でディスパッチしてください。agy には貼り付けた1つのプロンプトが12個の入力として送信され、GOAL と CONTEXT が届かないまま、assigned:true と報告されたことがあります。

agent-tmux codex result --json --wait 30 worker
agent-tmux codex supervise --result-required --silent-while-unchanged --json worker

.present:false の場合、エージェントはファイルを書き出していません。result --path <name> で得られるリテラルのパスを指定して、再度プロンプトを送信してください。完全なスキーマ、実例、status --json のフィールド、承認ゲートの終了コード、並行実行モデルについては references/contracts.md を参照してください。

安全性

• ラッパーはデフォルトで許可範囲の広い CLI フラグを使用します（Claude には --dangerously-skip-permissions、Codex には --yolo）。明示的なユーザーの許可なしに、破壊的な作業、プライバシーに関わる作業、外部に公開される作業、支払いを伴う作業、または取り消せない作業に使用しないでください。
• ペインが確認待ちのように見える場合、status --json は confirmation_detected:true と blocked_reason を報告します。自動承認は行いません。信頼できると判断した場合にのみ応答してください。
• 複数のワーカーを起動する前に、ワーカーごとにツール、モデル、処理の強度をユーザーに確認し、ワーカー数の上限を設定し、すべてのプロンプトで連鎖的な起動を禁止してください。詳細は references/multi-agent.md を参照してください。
• シークレットの注入（--secret KEY=URI、失敗時は閉鎖）と監査ログ（TMUX_AGENT_TOOLS_AUDIT_LOG）については references/security.md を参照してください。

参考資料

関連する状況になった場合にのみ、以下を読み込んでください。通常の使用では必要ありません。

• references/core-workflow.md — 単一ワーカーの完全なワークフロー、セッション名、リモートセッション、ピアレビュー、承認ゲート、インライン実行とワーカー実行の判断基準。
• references/profiles.md — カスタム CLI プロファイルのキー、優先順位、例、検出方法のオーバーライド。
• references/cheatsheets.md — 完全な機能一覧表、状況別のコマンド、マーカーに関する落とし穴、障害の切り分け。
• references/multi-agent.md — 対話／ファンアウトのルール、ブリッジパターン、SSH 参加者、github-comment の動作。
• references/contracts.md — status --json／result.json のスキーマ、承認の終了コード、並行実行、インベントリ／クリーンアップ。
• references/security.md — シークレットの注入、監査ログ、環境変数のオーバーライド、事前チェック。
• references/troubleshooting.md — 停止、未送信、古いマーカーが発生する状況の障害モードと修正方法。
• references/recipes.md — コピーしてすぐ使えるワークフロー（承認ゲート、ファンアウト、DAG）。

同梱スキーマ

schemas/ には result-status-summary.schema.json と fanout-summary.schema.json が含まれています。これらは、ディスク上にほかのコピーが見つからない場合に、スクリプトが result.json の検証用としてすでに参照するオフラインフォールバックです。

agents/ のサブエージェントバンドル（tmux-delegate.md、claude-oneshot.md、codex-oneshot.md）は廃止されました。詳細は CHANGELOG を参照してください。これらに含まれていたインライン実行とワーカー実行の判定、およびワンショット転送パターンは、現在 using-tmux-agent-tools スキルの判断ツリーにあります。~/.claude/agents/ にインストールするものはもうありません。