Worktree タスク

Worktree タスクは、エージェントに専用のブランチと作業ディレクトリを与える機能です。 エージェントは、利用者がチェックアウトしているファイルに触れずに作業できます。 Calyx がブランチとリンクされた Git worktree を作り、そのディレクトリでエージェントを起動した状態のタブを開きます。 作業が終わったら、ブランチをベースにマージするか、破棄します。

タスクの作成

New Worktree Task シートは、次のいずれかの方法で開きます。

• File → New Worktree Task…、または Cmd+Shift+N
• コマンドパレットの New Worktree Task…
• Changes サイドバーのヘッダーにある + ボタン

シートは、フォーカス中のペインの現在のディレクトリを対象にします。 そのディレクトリが Git リポジトリの中になければ、シートに Not inside a git repository と表示され、Create & Launch は押せません。

シートの項目は次のとおりです。

• Branch：新しいブランチの名前（例：task/my-change）。 Git のブランチ名として有効で、まだ存在しない名前である必要があります。
• Base：タスクの起点にするローカルブランチ。 ペインのディレクトリでチェックアウト中のブランチが標準で選ばれます。
• Agent：Claude Code、Codex、OpenCode、Hermes Agent、Grok、pi のいずれか。
• Arguments：エージェントに渡す追加のコマンドラインオプション（例：--model opus --effort high）。 シェルと同じ規則で単語に分けますが、シェルは実行しないため、$、~、グロブ、; はそのままエージェントに渡ります。 引用符が閉じていないときや、末尾がバックスラッシュのときは Create & Launch を押せません。 入力した内容は次のタスクには引き継がれません。
• Initial prompt：エージェントに最初のプロンプトとして渡す文章（省略可）。 Hermes Agent は初期プロンプトなしで起動するため、この欄は無効になります。

Create & Launch（Return）を押すと、~/.calyx/worktrees/<リポジトリ名>/<ブランチ名> に worktree を作り（ブランチ名のスラッシュはハイフンに置き換えます）、ベースブランチをそのリポジトリの Git 設定に branch.<ブランチ名>.calyxbase として記録し、現在のグループに新しいタブを開きます。 ディレクトリがすでにあるときや、ベースブランチが見つからないときは何も作らず、シートにエラーを表示します。 Cancel（Escape）はシートを閉じます。 プロンプト欄にフォーカスがあるときも Escape で閉じられます。

エージェントの動き方

エージェントはシェルに入力したコマンドとしてではなく、ペインのプロセスそのものとして起動します。 そのため、タブは最初の一行目からエージェントです。 永続セッションが有効なら、永続セッションの中で動きます。 .zshrc などで設定した PATH が効くように、Calyx は利用者のログインシェルを介してエージェントを起動します。 ログインシェルが csh、tcsh、fish、nu のときは、代わりに /bin/zsh を使います。

コマンドラインは、エージェントの CLI、利用者の Arguments、プロンプトの順で、プロンプトは一つの引数として渡します。 OpenCode には --prompt としてプロンプトを渡し、Hermes Agent には渡しません。 Claude Code、Codex、Grok では、Arguments があるときとプロンプトが - で始まるときに、オプションとプロンプトの間に -- を置きます。 pi では、プロンプトが - で始まるときだけ -- を置きます。

エージェントが終了すると、ペインは worktree のディレクトリで対話シェルとして続きます。 結果を確認したり、エージェントをもう一度起動したりできます。 エージェントが worktree を削除していた場合、シェルはタスクを作成したリポジトリで始まります。 そのシェルを終了すると、タブが閉じます。

ペインの Mission Map のカードには、タブを開いた時点から Task → <ベース> の行が表示されます。

タスクのマージと破棄

マージと破棄は、Changes サイドバーと Mission Map のどちらからでも実行できます。

• Changes サイドバーでは、タスクの worktree のセクションヘッダーにチェックリストのアイコンが付きます（ツールチップは Worktree Task → <ベース>）。 そのメニューに Merge into <ベース> と Discard があります。
• Mission Map のカードでは、Task → <ベース> の行に Merge と Discard のボタンがあります。

この操作ができるのは、Calyx がタスクとして作成した worktree（ブランチに calyxbase の記録があるもの）だけです。 ほかの worktree は、これまでどおりサイドバーに並びます。

Merge は、ベースブランチをチェックアウトしている worktree で、タスクのブランチを git merge --no-ff でマージします。 タスクの worktree に未コミットの変更（未追跡ファイルを含む）があるとき、ベースブランチがどの worktree にもチェックアウトされていないとき、その worktree でマージが進行中のときは、マージを実行しません。 コンフリクトなどでマージに失敗したときは、マージを取り消して Git のメッセージを表示し、タスクはそのまま残します。 マージに成功すると、Calyx は worktree を削除し、ブランチを削除し、すべてのウィンドウで worktree の中をディレクトリにしているペインを閉じ、その永続セッションも終了します。 ウィンドウにペインが一つも残らなくなる場合は、先にベースの worktree で新しいタブを開きます。

Discard は確認のあと、未コミットの変更ごと worktree を削除し、ブランチを強制削除し、ペインを同じように閉じます。

どちらの操作でも、エラーは Worktree Task というタイトルのアラートに表示されます。 処理中のタスクに対してもう一度マージや破棄を始めると、処理中である旨が表示されます。