tmux-worktree-session

tmux ワークツリーセッション

自己完結型の作業環境を立ち上げます。分離された git ワークツリー、作業を進めるための tmux セッション、起動済みの開発スタック、そしてブリーフィングに取り組み始めている新しいエージェントを用意します。 人間がアタッチした時点で、作業はすでに進行しています。

以下の 2 つのスキルを組み合わせます。安全にペインを操作する tmux-orchestration と、ブリーフィングを書く handoff です。

標準のレイアウト

Session: <Project>-<work>     (hyphenated, no spaces)
├── Window 1 "agent" → coding agent (Claude/Codex), cwd = worktree, given a
│                      kickoff prompt pointing at the briefing
├── Window 2 "cli"   → bare shell for tests and ad-hoc commands
└── Window 3 "dev"   → dev stack

ウィンドウは 3 つで、それぞれ 1 つの役割を担います。分割はありません。これが標準的な構成です。必要に応じて調整してください（開発スタックなし、エージェント 2 つ、ログ用ウィンドウなど）。判断が難しい場合は確認してください。ユーザーに頼まれない限り、git/lazygit ウィンドウは追加しないでください。

入力

問いただすのではなく、コンテキストから補ってください。

• 作業名 → ブランチ名とセッション名。PR 番号や issue 番号があれば、そちらを優先してください。
• エージェント + モード → Claude または Codex、fast または plan。不明な場合は一度だけ尋ねてください。
• ベースブランチ → 通常はデフォルトブランチです。ワークツリーツールは origin/<default> をベースにすることが多いため、手順 1 で重要になります。

手順

1. ブリーフィングを書き、まずベースブランチにコミットする

handoff を使って、エージェントが読む内容を書きます。ミッション、対象を絞ったタスク、ファイルやパターン、規約、ガードレールを含めます。履歴ではなく、ブリーフィングを書いてください。

ワークツリーツールが新しいツリーを origin/<default> ベースで作成する場合、ブリーフィングをベースブランチにコミットしてプッシュしてから、ワークツリーを作成してください。そうしないと、エージェントがブリーフィングを参照できません。

2. ワークツリーツールを見つけて実行する

思い込みで進めず、探してください（チートシートを参照）。よくある例：bin/worktree create <name>、bin/worktree create --pr 42。フォールバック：git worktree add ../<repo>-<branch> -b <branch> origin/<default>。

作成時に、依存関係、DB、シークレットなどを含む完全なブートストラップが実行されることがよくあり、数分かかります。停止したと決めつけないでください。シークレットの入力を求められる場合もあります（1Password、マスターキー、環境トークン）。承認するのはユーザーです。ユーザーに提示して待ち、自分で認証情報を入力してはいけません。可視ペインで実行し、開発スタックを起動する前に、実際の完了シグナルを確認してください（; echo DONE_$? を追加してポーリングします）。

3. 開発スタックとテストのコマンドを見つける

思い込みで進めず、探してください（チートシートを参照）。制御にはヘッドレス／デタッチモードを優先してください（例：process-compose の -D と status／logs）。人間が確認する場合は、フォアグラウンドの TUI でもかまいません。テストランナーを把握してください。cli ウィンドウとエージェントで必要になります。

4. セッションを構築する

仕組みは tmux-orchestration に従います。特に注意が必要な点：

• ユーザーの現在のセッションに影響しないよう、デタッチ状態で作成してください。
• ハイフン区切りの名前にし、スペースは使いません。
• ウィンドウ 1 agent：ワークツリーに cd してエージェントを起動します。UI の準備ができたら、キックオフ文をバッファー貼り付けし、その後 Enter を別の手順で送信してください。短くまとめ、ブリーフィングを参照するよう指示します。必要に応じて、エージェントが tmux CLI 経由で自分でポーリングできるよう、兄弟ペインの ID（cli、dev）を渡してください。
• ウィンドウ 2 cli：ワークツリーに cd して、テストやその場のコマンドに使うシェルを起動します。
• ウィンドウ 3 dev：ワークツリーに cd して、開発スタックを実行します。

すべてのウィンドウでワークツリーに cd し、適切なツールチェーンを使えるようにしてください（バージョンマネージャーの注意点を参照）。

5. 検証して報告する

• 開発スタックが実際に正常な状態であることを確認します（status／ヘルスチェックをポーリング）。単に「起動した」だけでは不十分です。失敗があれば、プロセスログを確認してください。
• エージェントが実際に起動したことを確認します（ペインの内容を取得し、貼り付けが届いたと決めつけないでください）。
• 次のコマンドを報告します：tmux attach -t <session>。

注意点

バージョン管理ツールは、起動したシェルでは有効になりません（最も重要な点です）。 プログラムから起動したシェル（tmux new-session、非ログインシェル）では、ユーザーのバージョン管理ツール（mise/asdf/rbenv/nvm）が読み込まれないことがよくあります。そのため、ruby/node/python が気付かないうちにシステムのバージョンにフォールバックし、ブートストラップに失敗します（例：「Could not find bundler」）。

• 検出方法：ペイン内の ruby -v などの出力と、ユーザーの出力を比較します。不一致があれば疑ってください。
• 対話型ペインでの修正方法：mise の場合は、シムを PATH に追加します。例：export PATH="$HOME/.local/share/mise/shims:$PATH"。
• 開発スタックの子プロセスも修正します：mise 管理ツールが必要な各コマンドの実行時に、eval "$(mise activate bash)" && …（または mise exec --）を実行します。

ペインの仕組みと安全性 → tmux-orchestration。 ペイン ID によるターゲット指定、自分のペインへの書き込み禁止、読み取り後の書き込み、複数行プロンプトのバッファへの貼り付け、Enter の個別送信などについては、すべてそちらで扱っています。ここでは繰り返さず、その手順に従ってください。ここで繰り返す価値がある点は 2 つです：セッション名にスペースを入れないこと（session:window ターゲットの解析に失敗します）。また、開発用 TUI は推測した Ctrl-C ではなく、実際のキー（process-compose の場合は F10）で終了してください。

検索の早見表

必要なもの	確認するもの
ワークツリー用ツール	bin/worktree、script/worktree、DEVSTACK.md、just/make、または git worktree add
開発スタック	bin/dev、npm/pnpm dev、foreman/overmind、process-compose、docker compose、mise run dev、プロジェクト固有のコマンド
テストランナー	bin/rspec、pnpm test、pytest、go test、Makefile
ツールチェーン	.mise.toml/.tool-versions/.ruby-version/.nvmrc — 起動したシェルで使用されていることを確認します