workmux

workmux

workmux は、Git worktree と tmux ウィンドウを組み合わせて、並行開発を管理します。各 worktree は、独自のブランチ、ターミナル状態、AI エージェントを備えた独立したワークスペースです。

ユーザーから worktree の作成やタスクの割り当て（例：/workmux add ...）を求められた場合、あなたはディスパッチャーです。 プロンプトファイルを作成し、コマンドを実行してください。コードベースの探索、閲覧、調査を先に行ってはいけません。すでに把握しているコンテキストを使用してください。作業は worktree エージェントがすべて行います。

プロジェクトでエージェントを起動する

ユーザーから <project> で新しいエージェントを開く、または起動するよう求められた場合、プロジェクト名を tmux セッション名として扱ってください。プロジェクトのディレクトリを特定し、その tmux セッションが存在する場合は再利用し、存在しない場合は作成してください。そのセッション内の新しいウィンドウで、プロジェクトのディレクトリを作業ディレクトリとしてエージェントを起動してください。ユーザーが指定したエージェント、または設定済みのデフォルトエージェントを使用してください。これは tmux 内のターミナルエージェントであり、アシスタントアプリ内の新しいチャットではありません。

既存のセッションの場合：

tmux new-window -d -P -F '#{window_id}' -t <project> -n <name> \
  -c <project-path> <agent>

セッションが存在しない場合は、最初のウィンドウでエージェントを起動して作成してください：

tmux new-session -d -P -F '#{window_id}' -s <project> -n <name> \
  -c <project-path> <agent>

既存のプロジェクトパスを特定するには、たとえば tmux list-sessions -F '#{session_name}\t#{session_path}' のように、tmux セッションのメタデータを使用してください。メタデータからパスを取得できる場合は、ディレクトリ一覧を避けてください。新しいウィンドウを作成する際は tmux new-window -d -P -F '#{window_id}' ... を使って新しいウィンドウ ID を取得し、その後の操作ではウィンドウ一覧を再取得せず、その ID を使用してください。切り替えが要求された場合は、クライアントの検索と切り替えを 1 回のツール呼び出しにまとめてください。切り替えは要求された場合にのみ行ってください。コマンドの成功結果ですでに処理の完了を確認できる場合は、冗長な確認呼び出しを避けてください。

別の worktree を使うとタスクに明らかに役立つ場合は、対象リポジトリから workmux add を使用してください。エージェントを目的の tmux セッションに配置するには、--parent-session <project> を渡してください。設定済みのデフォルトエージェントを使用するか、ユーザーから特定のエージェントを指定された場合は -a <agent> を渡してください。workmux は必要に応じて親セッションを作成します。それ以外の場合は、既存のプロジェクトのチェックアウトを使用してください。

エージェントの状態を確認する

把握済みのセッション、パス、ハンドルを再利用してください。ハンドルが不明な場合は、まずセッションのコーディネーターまたはダッシュボードを確認してください。

関連するエージェントについて、workmux status と workmux capture <handle> -n 50 を 1 回のツール呼び出しにまとめてください。アイドル状態のシェルや無関係なプロジェクトは対象外にしてください。タスク、進捗、ブロッカー、完了を示す証拠を報告し、状況が明確になったら終了してください。

主な概念

• ハンドル：ブランチ名からスラッグ化して生成される worktree ディレクトリ名です。すべてのコマンドで worktree を識別するために使用します
• worktree ディレクトリ：デフォルトでは <project>__worktrees/<handle> で、プロジェクトのルートディレクトリと同じ階層に置かれます
• ウィンドウのプレフィックス：tmux ウィンドウはデフォルトで wm-<handle> という名前になります（window_prefix で設定可能）
• エージェントの状態：エージェントはフックを通じて状態を報告します：作業中、待機中（入力が必要）、完了（終了）

コマンド

worktree を作成する

workmux add <branch-name>

Git worktree を作成し、ファイル操作とフックを実行して、設定されたペインレイアウトの tmux ウィンドウを作成し、そこに切り替えます。

主なフラグ：

• --pr <number|url>：番号または完全な URL を指定して GitHub プルリクエストをチェックアウトし、新しい worktree に配置します。ローカルブランチ名はデフォルトで PR のヘッドブランチ名になります。<branch-name> を渡すと、たとえば workmux add --pr https://github.com/owner/repo/pull/123 custom-name のように上書きできます。認証済みの gh が必要です。
• -b, --background：切り替えずに作成します
• -p <text>：AI エージェントのペインにインラインプロンプトを指定します
• -P <file>：ファイルからプロンプトを指定します
• -e, --prompt-editor：$EDITOR でプロンプトを記述します
• -A, --auto-name：LLM を使ってプロンプトからブランチ名を生成します
• -a <agent>：エージェントを上書きします（複数の worktree を作成する場合は複数指定できます）
• -w, --with-changes：未コミットの変更を新しい worktree に移動します
• --base <branch>：指定したベースブランチから分岐します
• --name <name>：worktree のハンドルを上書きします
• --target-name <name>：workmux が管理する tmux ウィンドウ名またはセッション名を上書きします
• --parent-session <session>：ウィンドウモードの対象をこの tmux セッションに配置します。存在しない場合は親セッションを作成します
• -o, --open-if-exists：既存の worktree がある場合は開きます（冪等）
• -W, --wait：tmux ウィンドウが閉じるまで待機します
• -n, --count <N>：N 個の worktree インスタンスを作成します
• --foreach <matrix>：変数マトリックスから worktree を作成します
• --no-hooks, --no-file-ops, --no-pane-cmds：セットアップ手順をスキップします

マルチプレクサーなしで作成する

workmux add <branch-name> --headless --json

ウィンドウを作成したりエージェントを起動したりせずに、ファイル操作と作成後のフックを実行します。マルチプレクサーが実行中である必要はありません。--json には --headless が必要で、ハンドル、worktree のパス、有効な作業ディレクトリを含む JSON レシートを 1 つ返します。フックの出力は stderr に送られます。

明示的なローカルブランチ名を使用してください。--base、--name、--no-hooks、--no-file-ops をサポートしますが、PR のチェックアウト、プロンプト、--background、その他のマルチプレクサー／エージェント関連オプションはサポートしません。worktree は削除するまで残ります。workmux remove <handle> でクリーンアップするか、後から workmux open <handle> でウィンドウを開いてください。

worktree を一覧表示する

workmux list          # all worktrees
workmux list --pr     # with GitHub PR status
workmux list <name>   # filter by handle or branch

ブランチ、エージェントの状態、tmux ウィンドウの状態、未マージのコミットを表示します。

ブランチをマージする

workmux merge                 # merge current branch into main
workmux merge <branch>        # merge specific branch
workmux merge --rebase        # rebase before merging (linear history)
workmux merge --squash        # squash all commits into one
workmux merge --into <branch> # merge into a different target branch
workmux merge --keep          # merge but keep worktree/window/branch
workmux merge --notification  # show system notification on success

ブランチをマージし、tmux ウィンドウを削除して、worktree とローカルブランチを削除します。ワークフロー全体（コミット、リベース、その後のマージ）には /merge スキルを使用してください。

worktree を削除する

workmux remove                # current worktree
workmux remove <name>...      # specific worktrees
workmux rm --gone             # worktrees whose remote branch was deleted
workmux rm --all              # all worktrees
workmux rm -f <name>          # force, skip confirmation
workmux rm --keep-branch      # keep the branch, remove worktree + window

ウィンドウを開く／閉じる

workmux open <name>           # open or switch to tmux window
workmux open --new            # force a new window (creates suffix -2, -3)
workmux open <name> -p "..."  # open with a prompt for agent panes
workmux close <name>          # close tmux window, keep worktree

他のエージェントとやり取りする

これらのコマンドは、worktree のハンドルを指定してエージェントを対象にします。現在のリポジトリでハンドルが見つからない場合、workmux はすべてのアクティブなエージェントを対象に検索します。名前が重複する場合は、project:handle の形式を使って区別してください。

# Check agent statuses
workmux status                          # all agents
workmux status auth api-tests           # specific agents

# Wait for agents
workmux wait agent-a agent-b            # block until done
workmux wait agent-a --timeout 3600     # with timeout (seconds)
workmux wait agent-a agent-b --any      # wait for first to finish
workmux wait agent-a --status working   # wait for specific status

# Read agent terminal output
workmux capture agent-a                 # last 200 lines (default)
workmux capture agent-a -n 50           # last 50 lines

# Send instructions to an agent
workmux send agent-a "fix the tests"    # short message
workmux send agent-a "/merge"           # send a skill command
workmux send agent-a -f followup.md     # from file
workmux send myproject:docs "update the API section"  # cross-project

# Run shell commands in an agent's worktree
workmux run agent-a -- pytest tests/    # wait and stream output
workmux run agent-a -b -- npm run build # run in background

その他のコマンド

workmux path <name>           # print worktree filesystem path
workmux dashboard             # TUI dashboard of all active agents
workmux config edit           # open global config in $EDITOR
workmux config reference      # print default config with all options documented
workmux init                  # generate .workmux.yaml in current project

設定

設定はグローバル（~/.config/workmux/config.yaml）とプロジェクト（.workmux.yaml）の 2 つのレベルがあります。プロジェクトの設定はグローバル設定を上書きします。

主なオプション

agent: claude                    # default agent for <agent> placeholder
merge_strategy: rebase           # merge, rebase, or squash
mode: window                     # window or session

panes:
  - command: <agent>             # <agent> resolves to configured agent
    focus: true
  - split: horizontal            # second pane with shell

files:
  copy:
    - .env                       # copy from main worktree
  symlink:
    - node_modules               # symlink from main worktree

post_create:
  - '<global>'                   # include global hooks
  - npm install                  # project-specific setup

base_branch: develop             # default base for new worktrees
window_prefix: wm-               # tmux window name prefix

プロジェクト設定の配列で '<global>' を使うと、グローバルの値を含められます。

すべてのオプションを記載した設定リファレンス全体を確認するには、workmux config reference を実行してください。

エージェントの検出

組み込みエージェント（claude、gemini、codex、opencode、kiro-cli、vibe）はペインコマンド内で自動検出され、プロンプトが自動的に注入されます。<agent> プレースホルダーには、設定されたエージェントが割り当てられます。

一般的なワークフロー

作業の完了：直接マージ

/merge を使うと、ベースブランチへのコミット、リベース、マージを一度に実行できます。これにより、worktree、tmux ウィンドウ、ブランチがクリーンアップされます。

作業の完了：PR を使用する方法

1. 変更をコミットします
2. git push -u origin HEAD
3. /open-pr を使って PR の説明を作成し、ブラウザーで開きます
4. PR がリモートでマージされた後、workmux rm --gone でクリーンアップします

タスクを委任する

/worktree を使うと、タスクを並列の worktree エージェントに割り当てられます。エージェントがプロンプトファイルを作成し、workmux add -b -P <file> を実行します。

起動、監視、マージを含むライフサイクル全体のオーケストレーションには、/coordinator を使用してください。

プロジェクトをまたいだワークツリーの作成

workmux add は、現在の作業リポジトリにワークツリーを作成します。コマンドの作業ディレクトリを対象プロジェクトに設定し、--parent-session を渡すと、管理対象のウィンドウを特定の tmux セッションに直接配置できます。作業ディレクトリと tmux セッションはそれぞれ独立しています。バックグラウンドやエージェントのツール呼び出しでは $TMUX_PANE が省略される場合があるため、配置が重要な場合は、連携して実行する際に必ず --parent-session を渡してください。Workmux は親セッションが存在しない場合に作成するため、tmux new-window や tmux new-session で事前に作成する必要はありません。

# Run with the command working directory set to <project-path>
workmux add <branch> -b -P <prompt-file> --parent-session <session>

管理対象の tmux ターゲットに、ワークツリーから導出されるデフォルトとは異なる名前が必要な場合に限り、--target-name <name> を使用してください。正しい Git リポジトリとベースブランチからワークツリーを作成できるよう、対象リポジトリから workmux コマンドを実行してください。

ディスパッチの前に調査しないでください。すでに把握しているコンテキストを使い、プロンプトを書くためだけにコードを調べたり読んだりしないでください。ワークツリーエージェントは絶対パスを使って他のプロジェクトのファイルを読めるため、他のプロジェクトはパスで指定し、エージェント自身に調査させてください。

関連スキル

• /merge：現在のブランチをコミット、リベース、マージします
• /rebase：スマートなコンフリクト解決でリベースします
• /worktree：並列ワークツリーエージェントにタスクを委任します
• /coordinator：複数のエージェントを統括します（起動、監視、マージ）
• /open-pr：PR の説明を作成し、ブラウザーで開きます