Orcaの使い方を解説！インストールから並列作業・レビュー・PR作成まで

Claude Codeをターミナルで使っていて、2つ目の修正を頼みたいのに1つ目の作業が終わるまで待っている場面があります。Orcaを使うと、修正ごとにworktreeを作って別々のAIエージェントを同時に走らせ、差分を並べて確認できる環境です。

この記事では、Orcaのインストールと初期設定・AIへの指示・レビューからプルリクエスト作成までの手順を解説します。記事を読めば、Orcaで最初の作業を1件完了させ、2つ目のエージェントを追加する準備が整います。最初は1つのエージェントで一巡し、慣れてから並列に増やす進め方が確実です。

Orcaの使い方の全体像

Orcaは、Gitのworktreeごとに1つのAIエージェントを起動し、変更をレビューしてコミットするまでを1つの画面で進める開発環境です。Orcaの役割や料金を先に確認したい場合は、Orcaとは何かで整理しています。使い始める前に用意するものは、以下の3つです。

• Gitで管理されたリポジトリ(コミットが1件以上あるもの)
• インストールとログインを済ませたAIエージェントのCLI(Claude Code・Codexなど)
• 対応OSのパソコン(macOS・Windows 10と11の64bit版・Linux)

Orcaはエージェントを起動する側のアプリなので、Claude CodeやCodexのインストールとログインは公式の手順で先に済ませます。Orcaの初回ガイドに沿った最初の作業は、以下の順序です。最初のセッション

1. OSに合うOrcaをインストールして初期設定を確認する
2. サイドバーの「Add Repo」(新しい版では「Create」メニュー)でリポジトリを登録する
3. リポジトリ名の横の「＋」でworktreeを作り、エージェントを選ぶ
4. ターミナルに指示を入力し、状態記号で進捗を追う
5. 差分ビューアで変更を読み、Annotate AI Diffで修正を依頼する
6. コミット・プッシュしてプルリクエストを作り、worktreeを片付ける

1件目は、検証用のリポジトリで小さな修正を選ぶ方法がおすすめです。依頼から確認までの流れを覚えてから、2つ目のworktreeとエージェントを足すと、操作と結果の対応を把握しやすくなります。

Orcaのインストールと初期設定

Orca本体は無料で、公式サイトとGitHubのリリースページから入手できます。初期設定で確認する項目は、以下の4つです。

• OSに合う配布ファイルを選んでインストールする
• 初回起動で表示言語と通知、Windowsのシェルを設定する
• AIエージェントの検出と既定のエージェントを確認する
• 権限モードをYoloからManualへ切り替える

OSに合う配布ファイルを選んでインストールする

公式のインストールページでは、OSごとに配布ファイルが用意されています。選び方は、以下の表のとおりです。Orcaのインストール

macOS版は署名と公証が済んでいますが、初回起動時にmacOSが確認ダイアログを出す場合があります。公式ページには、Electron製アプリでは通常の挙動だと書かれています。Homebrewで入れた場合の更新は「brew upgrade --cask orca」です。

Linux版のコマンド名が「orca-ide」なのは、GNOMEの画面読み上げソフトOrcaと名前が衝突しないようにするためです。AppImage版は自動更新に対応し、debとrpmは手動で更新します。更新は既定で安定版チャンネルを追い、新機能を先に試すRC版は、Settings→General→Updatesの「Check for Updates」をShiftキーを押しながらクリックすると取得できます。

初回起動で表示言語と通知、Windowsのシェルを設定する

初回起動後は、Settings→Appearance→Languageで表示言語を「日本語」に変更できます。macOSの日本語キーボードで円記号がバックスラッシュとして入力されない場合は、Settings→Terminalの「JIS Yen (¥) to Backslash (\)」が対処法です。設定リファレンス

通知の設定場所はSettings→Notificationsです。エージェントの完了をOSの通知・通知音・worktree上のチップで知らせるかを選べ、プルリクエストのチェック失敗やアプリの更新も通知対象に含められます。Orcaの通知

Windows版では、ターミナルの既定シェルをPowerShell・コマンドプロンプト・WSLから選びます。設定場所はSettings→Terminalで、タブのドロップダウンから一時的に切り替える操作も可能です。Codexは、Windows側にインストールしたものとWSLのディストリビューション内のものの両方を起動対象にできます。ターミナル、Codexの設定

AIエージェントの検出と既定のエージェントを確認する

Orcaは、PATHに登録されたエージェントのCLIを自動で検出します。Claude Codeは「~/.claude」の設定を、Codexは「~/.codex」を読む仕組みで、検出結果はSettings→Agentsの「Installed agents」で確認と有効・無効の切り替えが可能です。通常のターミナルでCLIが起動する状態にしてからOrcaを開くと、検出漏れを防げます。対応エージェント、Claude Codeの設定

既定のエージェントは、Settings→Agentsで指定します。新しいworktreeを作るとき、既定のエージェントが最初に選ばれた状態で起動する設定です。普段Claude Codeだけを使っている人は、Claude Codeを既定にして1件目の作業を進めると、覚える操作を減らせます。

Cursor CLIを使う場合は、Cursorの公式手順でインストールして1度ログインしておくことが前提です。エージェントの選択欄で「Cursor」を選ぶと、対象のworktreeでCLIが起動します。使用するモデルはCursor CLI側の設定に従い、Orcaは上書きしません。Cursor CLIの利用

権限モードをYoloからManualへ切り替える

Orcaの既定では、エージェントの起動時に権限確認を省略するフラグが自動で付きます。公式ドキュメントには、Claude Codeなら「--dangerously-skip-permissions」を付与すると明記されています。Codexなら「--dangerously-bypass-approvals-and-sandbox」、GeminiやCursorなら「--yolo」が付与される対象です。理由は、worktreeが使い捨てにできるため、確認を省略しても差分ごと捨てられる点だと公式は説明しています。権限フラグの既定

業務のコードで使う場合は、最初にSettings→Agents→Agent Permissionsを開き、「Yolo」から「Manual」へ切り替えます。Manualにすると、ファイルの編集やコマンドの実行のたびにエージェント側の確認が表示される状態に戻る仕組みです。個別に起動引数を変更したエージェントは全体設定の対象外なので、変更済みのエージェントは起動引数も確認します。

worktreeで分かれるのは編集対象のファイルだけで、パソコンのほかのフォルダやネットワークへのアクセスは制限されません。確認を省略したまま使うかは、扱うコードと接続先の重要度で判断します。

リポジトリの登録からworktree作成まで

最初の作業は、手元のリポジトリを登録して修正用のworktreeを作るところから始まります。手順は、以下の3段階です。

• Add Repoでリポジトリを登録する
• 「＋」でworktreeを作りエージェントを選ぶ
• 依存関係と設定ファイルを新しいworktreeに用意する

Add Repoでリポジトリを登録する

サイドバーの「Add Repo」をクリックし、手元にあるリポジトリのフォルダを選びます。2026年9月9日公開のv1.4.199では、プロジェクトの追加とworkspaceの新規作成が1つの「Create」メニューにまとめられたと変更履歴に記載された変更点です。画面に「Add Repo」が見当たらない場合は、Createメニューから同じ操作を選びます。OrcaはGitの状態を読み取り、既定ブランチ(通常はorigin/main)を「base ref」として扱う仕組みです。base refは、worktreeの作成元やプルリクエストの比較先になる基準です。最初のセッション、変更履歴

複数のリポジトリを含むフォルダは、プロジェクトグループとしてまとめて登録できます。Claude Codeなどが外部で作ったworktreeも、Settings→General→Workspaceの設定でサイドバーに表示できます。worktreeの管理

「＋」でworktreeを作りエージェントを選ぶ

リポジトリ名の横の「＋」をクリックすると、worktreeの作成ダイアログが開きます。入力と選択の順序は、以下のとおりです。worktreeの作成

1. 作業内容がわかる名前を入力する(空欄なら海の生き物の名前が自動で付く)
2. 「Run on」で実行場所(手元のパソコンかSSH接続先)を選ぶ
3. 「Start-from ref」で開始地点のブランチやコミットを確認する(既定はbase ref)
4. 「Agent selector」で起動するエージェントを選ぶ(空のターミナルも選べる)
5. 必要ならGitHubのIssueやLinearの課題を貼り付けて関連付ける
6. 作成を実行し、サイドバーの進捗表示を待つ

ダイアログで選んだエージェントは、新しいworktreeのターミナルにあらかじめ選択された状態で表示されます。作成はバックグラウンドで進み、ダイアログはすぐに閉じます。裏では「git fetch」と「git worktree add」が実行され、サイドバーに状態が表示される仕組みです。Issueを関連付けた場合は、課題の内容からブランチ名が自動で決まります。

Start-from refを取り違えると、修正の前提になるコードが変わります。依頼に必要な変更が入っているブランチを選ぶことが、作業内容の食い違いを防ぐために大切です。ブランチ名を自分で決めたい場合は、「Advanced」を開いて入力します。

依存関係と設定ファイルを新しいworktreeに用意する

新しいworktreeには、Gitで管理されていないファイルが含まれません。node_modulesのような依存ライブラリや.envのような設定ファイルは、元のフォルダにあってもコピーされないためです。Orcaには、不足を補う方法が3つ用意されています。worktreeの共有とコピー

• Worktree Shared Paths(Settings→Repository)で、Git管理外のフォルダを元のチェックアウトからシンボリックリンクで共有する
• リポジトリ内のorca.yamlに共有するフォルダを列挙する
• リポジトリ内の.worktreeincludeに、コピーしたいGit管理外のファイルを列挙する

依存ライブラリのインストールを自動化したい場合は、Settings→Repository→HooksのWorktree Setup Hooksにコマンドを登録します。worktreeの作成後に「pnpm install」のようなコマンドが実行される仕組みです。hooksとメモリ

共有とコピーでは、元のファイルへの影響が異なります。共有したフォルダをエージェントが書き換えると、元のチェックアウトにも変更が及ぶ点に注意が必要です。本番環境の認証情報を含む設定ファイルは共有やコピーの対象に含めず、検証用の値に差し替えたファイルを用意します。

AIエージェントへの指示と作業の見守り方

worktreeができると、選んだエージェントが専用のターミナルで起動します。指示から完了確認までの操作は、以下の3つです。

• エージェントを起動して指示を入力する
• 状態記号と通知で進捗を追う
• 複数のworktreeを並べて切り替える

エージェントを起動して指示を入力する

新しいworktreeのターミナルには、エージェントの選択欄(agent combobox)が表示されます。Claude Code・Codex・Cursor CLIなどを選ぶと、worktreeのフォルダを作業ディレクトリとしてCLIが起動する仕組みです。指示は、普段のCLIと同じくターミナルに入力します。最初のセッション

Settings→Experimentalの「Chat UI」を有効にすると、対応エージェントの会話を構造化されたチャット画面で表示できます。ファイルや画像の添付・モデルの選択にも対応しますが、実験的機能でターミナル側の表示が正となる位置付けです。チャットUI

AIへの依頼は、達成したい状態と変更範囲を具体的に書きます。「使いやすくして」だけでは、エージェントがどこまで変更すればよいか判断できません。問い合わせフォームを修正する場合の指示例は、以下のとおりです。

• 目的: 必須項目が未入力のときに案内文を表示する
• 対象: 問い合わせフォームの画面と関連するテスト
• 維持する動作: 正しく入力した場合の送信処理
• 完成条件: 未入力で送信されず、該当箇所に案内が表示される
• 報告: 変更したファイルと実行した確認結果

指示例は作業範囲を決めるためのひな形なので、実際のファイル名や確認方法に合わせて書き換えます。1件目の作業では、完了報告が届いた後に何を確認するかも先に決めておきます。

状態記号と通知で進捗を追う

エージェントの状態は、タブとサイドバーの記号でわかります。記号ごとの意味と、見たときに取る行動は以下の表のとおりです。エージェントとセッション

作業が終わると、Settings→Notificationsの設定に応じてOSの通知と通知音が届き、ヘッダーのベルアイコンに未読数が付きます。通知をクリックすると該当のworktreeへ移動し、右クリックの「Mark unread」で未読に戻せる仕組みです。Orcaの通知

サイドバーの「Agents」を開くと、完了報告や質問、新しいworktreeの作成が時系列で並びます。実行中のエージェントは上部に固定され、Cmd+F(WindowsとLinuxはCtrl+F)で絞り込みが可能です。席を外していた後に、確認が必要なエージェントを探す画面として使えます。Agentsフィード

複数のworktreeを並べて切り替える

2件目の作業を足すときは、同じ手順でworktreeをもう1つ作り、別のエージェントを選びます。worktreeのタブをペインの右端へドラッグすると左右に、下端へドラッグすると上下に画面が分割される仕組みです。分割は入れ子にでき、配置はworktreeごとに保存されます。タブ・ペイン・分割

worktreeの切り替えには、Cmd+Jのジャンプパレットが便利です。最近使ったチャットやターミナル、worktreeを検索でき、プルリクエストの番号でも探せます。Cmd+Pは現在のworktree内のファイルを開くクイックオープンです。クイックオープン

並列化の用途は、独立した仕事を分担する使い方と、同じ課題を複数のエージェントに解かせて比較する使い方の2つです。公式のレシピでは、同じ開始地点から3つのworktreeを作り、Claude Code・Codex・Cursor CLIに同じ指示を貼り付けて差分を見比べる手順が紹介されています。エージェントごとに間違え方が異なるため、並列に走らせるほうが順番にやり直すより安い、と公式レシピは説明しています。複数エージェントの比較

変更のレビューからコミット・プルリクエストまで

エージェントの完了報告を受け取ったら、変更を読んで採否を決めます。レビューから統合までの操作は、以下の4つです。

• 差分ビューアで変更を読む
• Annotate AI Diffで修正を依頼する
• Design Modeで画面から指示する
• コミット・プッシュしてプルリクエストを作る

差分ビューアで変更を読む

差分ビューアには、ステージ済み・未ステージ・未追跡のファイルをまとめた差分が、開始地点のブランチとの比較で表示されます。キーボードでは、jとkでファイルを移動し、nとpで変更の塊を移動できます。sを押すと、カーソル位置の塊だけをステージする操作です。差分ビューア

差分ビューアの余白には、AIが書いた行を示す目印が表示されます。人が書き換えた行は目印が外れるため、AIの変更だけを重点的に読む使い方が可能です。目印の情報は手元にだけ保存され、コミットには含まれません。変更の帰属表示

外部のターミナルでGitを操作した後に表示が古いままの場合は、差分ツールバーの更新アイコンでworktreeを読み直します。差分を読む観点は、公式のレシピにある「必要な変更か・最小限か・ほかのコードと整合しているか」の3点が目安です。差分レビューのレシピ

Annotate AI Diffで修正を依頼する

差分に直接コメントを書き、まとめてエージェントへ返す機能がAnnotate AI Diffです。操作の順序は、以下のとおりです。Annotate AI Diff

1. 差分の対象行にカーソルを合わせ、余白の「＋」をクリックする(またはcキーを押す)
2. Markdownでコメントを書き、Cmd+Enter(WindowsとLinuxはCtrl+Enter)で保存する
3. ほかの行にも同じ手順でコメントを追加する
4. 差分の上部にある「Send to agent」をクリックする
5. 「Send notes to」のメニューで送信先のエージェントを選ぶ
6. 修正後に指摘が解消したコメントを「Resolve」で畳む

Orcaはすべてのコメントを行番号付きの1つの指示にまとめて送ります。コメントは対象の行に固定され、編集で行がずれても追従する仕組みです。未解消のコメントは次回の送信にも含まれるため、指摘の見落としを防げます。

例えば「未入力時の案内を追加する」と「正常時の送信処理は変えない」を別の行に書き、1回で送る使い方です。チャット欄で場所を説明し直す手間がなくなります。修正後は、コメントの内容が満たされたかを差分で再確認します。

Design Modeで画面から指示する

Webアプリの見た目を直す場合は、worktreeごとに内蔵されたブラウザでアプリを開き、Design Modeで対象を指定します。操作の順序は、以下のとおりです。Design Mode

1. 内蔵ブラウザで開発中のアプリのURLを開く
2. ブラウザのツールバーで「Design Mode」を有効にする
3. 修正したい要素をクリックする
4. 注釈トレイに希望する変更を書く(複数の要素に書ける)
5. まとめてエージェントへ送る

クリックした要素のHTMLと計算済みのCSS、切り抜いたスクリーンショットが1つの添付として送られます。開発用のソースマップがあれば、対応するソースファイルの位置も含まれる仕組みです。「上から3番目のボタン」と文章で説明する代わりに、対象を指して伝えられます。

修正後は、内蔵ブラウザで同じ画面を開き直して結果を確かめる手順です。見た目の変更が別の画面幅に影響していないかも、ビューポートの切り替えで確認できます。内蔵ブラウザ

コミット・プッシュしてプルリクエストを作る

採用する変更が決まったら、差分ビューアの横のコミットパネルで記録します。ファイル単位か変更の塊単位でステージし、メッセージを書くか「Generate with AI」で生成して、Cmd+Enter(WindowsとLinuxはCtrl+Enter)でコミットする流れです。pre-commitフックが失敗した場合は、出力がその場に表示され、「Fix with AI」で既定のエージェントに修正を依頼できます。コミットとプッシュ

「Push」は、初回のプッシュで自動的に上流ブランチを設定します。リモートが進んでいる場合に黙って強制プッシュすることはなく、必要なときだけ「Force push with lease」が別のボタンとして表示される仕様です。プッシュ後は、Source Controlパネルからプルリクエストを作成し、比較先のブランチ・タイトル・説明・下書きかどうかを指定します。説明文は「Generate pull request details with AI」で生成できます。

対応する開発プラットフォームはGitHub・GitLab・Bitbucket Cloud・Azure DevOps・Giteaです。GitHubはSettings→IntegrationsのOAuthで接続し、エラーの診断にはGitHub CLI(gh)の認証状態が使われます。作業が終わったworktreeは、Cmd+Shift+Backspace(WindowsとLinuxはCtrl+Shift+Backspace)で削除するか、Resource Managerの「Clean up workspaces」でまとめて整理します。GitHub連携、worktreeの整理

スマートフォンやSSH接続先からOrcaを使う方法

手元のパソコンで基本操作を覚えたら、外出先からの確認や別マシンでの実行に広げられます。設定する項目は、以下の2つです。

• モバイル連携アプリをペアリングする
• SSHターゲットで別のマシンにworktreeを作る

モバイル連携アプリをペアリングする

Orcaのモバイル連携アプリは、iOSとAndroid向けのベータ版です。iOS版はApp Storeから、Android版はGitHubのリリースページのAPK(2026年9月時点でバージョン0.0.48)から入手します。公式ドキュメントでは「すでに動いているデスクトップのリモコン」と位置付けられ、フル機能のエディタではありません。モバイル連携

ペアリングの手順は、以下のとおりです。

1. デスクトップ版のアカウントメニューからペアリング用のコードを発行する
2. スマートフォンのアプリで「Pair」を選び、コードを貼り付ける
3. 接続経路として「Orca Relay」(Orcaアカウントへのサインインが必要)か同じLAN内の接続を選ぶ

ペアリング後に可能な操作は、worktreeの状態確認・ターミナル出力の閲覧・入力待ちのエージェントへの返信(文字・写真・音声入力)・保存済みコマンドの実行・コミットなどです。スマートフォン単体でエージェントは動かず、デスクトップ側のOrcaが起動して接続できる状態を保つ必要があります。Android版のAPKは、公式ページの手順に従ってインストール許可を一時的に与える形です。Android版の導入

SSHターゲットで別のマシンにworktreeを作る

別のマシンでエージェントを動かしたい場合は、Settings→SSHの「Add Target」でホスト名・ユーザー名・ポート・鍵ファイルを登録します。「~/.ssh/config」からの取り込みも可能です。worktreeの作成ダイアログで「Run on」に登録したターゲットを選ぶと、エージェントとGitの処理は接続先で動きます。エディタ・差分・ブラウザは手元で表示される構成です。SSH接続

接続先には、Gitに加えてNodeとビルド用のツール(make・g++またはclang++・python3)が必要です。接続先のエージェントCLIも、接続先側でインストールとログインを済ませます。ノートパソコンがスリープしても接続先の作業は続き、Orcaが再接続してターミナルを再表示する仕組みです。トラブルシューティング、リモートworktreeのレシピ

リポジトリとエージェントをすべてサーバー側に置くリモートOrcaサーバーは、ベータ版として提供されています。公式ドキュメントには、Orcaのポートを公開インターネットへ直接転送しないよう明記されており、TailscaleのようなプライベートネットワークとOrcaを両方の端末に入れる構成が推奨されています。リモートOrcaサーバー

Orcaの操作でつまずいたときの確認方法

操作が進まないときは、AI側の問題とOrca側の問題を切り分けます。公式のトラブルシューティングにある症状と確認方法は、以下の表のとおりです。トラブルシューティング

通常のターミナルでもエージェントが起動しない場合は、AI側のインストールや認証の問題です。Orcaの中だけで起動しない場合は、Settings→Agentsの検出設定を確認します。切り分けてから対処すると、確認する対象を狭められます。

Orcaは2026年3月の公開以降も更新が頻繁で、2026年8月3日のv1.4.167から9月11日のv1.4.200まで約40日で30回以上のバージョンが公開されている状況です。更新が早い分、ボタンの名前や設定の位置が記事と異なる可能性があるため、迷ったら公式ドキュメントの最新版を参照します。チャットUIやエージェントのダッシュボードなどの実験的機能は、検証用のプロジェクトで試してから業務に使う進め方が安全です。変更履歴

Orcaの使い方は1件の作業を一巡させてから並列に広げよう

Orcaの基本は、リポジトリを登録してworktreeでエージェントを起動し、差分を確認してコミットする流れです。インストール直後に多数のエージェントを動かすより、1つのエージェントで小さな修正を完了させる進め方が操作の理解につながります。

最初の1件で確認したい項目は、以下のとおりです。

• Agent PermissionsをManualに切り替えたか
• 指定したworktreeで既定のエージェントが起動したか
• 依頼した範囲だけが差分に含まれているか
• Annotate AI Diffで修正の往復ができたか
• コミットとプルリクエストの作成まで進められたか

1件を完了できたら、独立した仕事を2つ目のworktreeに足し、分割表示で並べてみましょう。並列化で得られる効果の見極め方はOrcaのメリットで、既存のエディタとの使い分けはOrcaとVS Codeの比較で確認できます。