opencode-isolate

English README

エージェントの作業を git worktree に隔離する OpenCode プラグインです。セッションを離れる必要はありません。

エージェントにブランチでの作業開始を依頼すると、以降の会話は .worktrees/<ブランチ名>/ 配下の独立した作業ディレクトリで続行されます。メインの checkout は、未コミットの変更も含めてそのまま保たれます。

なぜ必要か

エージェントが checkout 内のファイルを直接編集すると、エージェントの変更と自分の変更が混ざってしまいます。変更を分けてレビューすることができず、ブランチの切り替えは開いているエディターと衝突し、失敗した実験はゴミとして残ります。git worktree はブランチごとに独立したディレクトリを与えることでこの問題を解決しますが、作成・除外設定・移動を手作業で管理するのは手間がかかります。

このプラグインを使うと、その隔離が一言の依頼で完了します。いま開いているセッションがそのまま worktree の中で続くため、新しいターミナルも新しいセッションも不要で、会話の文脈も失われません。

何をするか

プラグインは worktree_start という 1 つのツールを提供します。エージェントがブランチ名を指定してこのツールを呼び出すと、次の処理を行います。

1. リポジトリー直下の .worktrees/<ブランチ名>/ に git worktree を作成する。ブランチが存在しない場合は新規に作成し、存在する場合はそのまま使用する。
2. .git/info/exclude に .worktrees/ を追記し、worktree が git status に現れないようにする。チームで共有する .gitignore には手を加えない。
3. 現在のセッションの作業ディレクトリを worktree へ切り替える。以降のファイル編集とシェルコマンドは、すべて隔離されたディレクトリの中で実行される。

このツールは冪等です。同じブランチ名で再度呼び出した場合は既存の worktree を再利用し、セッションの切り替えのみを行います。作業がマージされたあとは git worktree remove でディレクトリを削除してください。

インストール

opencode.json の plugin 配列にパッケージ名を追加します。OpenCode が起動時に自動でインストールします。

{
  "plugin": ["opencode-isolate"]
}

使い方

OpenCode のセッションで、ブランチ名を添えて作業の隔離を依頼します。

worktree_start で 123-fix-login-bug ブランチの作業を始めて

エージェントが worktree を作成し、セッションがそこへ移動したら、あとは普段どおり会話を続けるだけです。その間、元の checkout は手を付けたときのままの状態で残ります。

制限事項

セッションの切り替えは、OpenCode のローカルセッションデータベースを更新することで実現しています。これは公開 API ではなく OpenCode の内部実装であるため、将来のリリースでスキーマが変わる可能性があります。切り替えが動作しなくなった場合は Issue で報告してください。

開発

実行環境には Bun を使用します。テストは次のコマンドで実行します。

bun test

ライセンス

MIT License です。詳細は LICENSE を参照してください。