🐋 複数のCLIエージェントをworktreeで並列に走らせるADE Orcaの構造と使い方

Orca は、複数のコーディング用 CLI エージェントを 1 つのデスクトップアプリから並列に走らせる ADE（Agent Development Environment）です。
この記事では、Orca の構造、データの置き場所、導入から CLI 操作、リモート実行、運用時の確認点までを、公式ドキュメントと公開リポジトリ stablyai/orca をもとに整理します。
数値とパスは 2026-10-03 時点の値です。

この記事の全体像。以下、順に解説します。

Orcaとは

Orca は、タスクごとに実在の git worktree、エージェント端末、ブラウザタブを割り当てる ADE です。
推論モデルは同梱しません。
利用者は、既に契約している Claude Code、Codex、OpenCode などの CLI を、その契約のまま起動します。
各 worktree は通常の git worktree なので、端末から git をそのまま使えます。
既定の実行場所は利用者のデスクトップです。
遠隔で動かす場合は、利用者が管理する SSH 先、自前の Orca サーバ、または利用者が契約するクラウド上の使い捨て環境を使います。

出典: stablyai/orca README

公式の What is Orca? は、次の 4 つの使い方を挙げています。

• 同じ不具合を複数エージェントに並行して試させ、結果を選ぶ。
• AI が作った差分を、出荷前に差分ビューで読む。
• 既存の Claude Code、Codex、Cursor CLI の契約を 1 つの操作面にまとめる。
• SSH、自前の Orca サーバ、オンデマンド VM へエージェントを逃がしても、手元の IDE 面を残す。

想定する利用者は、差分とコミットを自分で読む開発者です。
ライセンスは MIT（Copyright (c) 2026 Lovecast Inc.）で、主言語は TypeScript です。

2026-10-03（JST）に GitHub API で読んだ公開リポジトリの指標は次のとおりです。

repos と Search は別エンドポイントです。
取得の瞬間によっては、issue と PR の合計が open_issues_count と 1 件ずれることがあります。

デスクトップ版は macOS、Windows、Linux 向けです。
モバイル版は iOS の App Store アプリと Android APK です。
ホームページには Y Combinator のバッキング表示があります。

周辺の仕組みとの関係は、公式の定義では次のとおりです。

ホームページの比較表と、ドキュメントの実行モードを合わせると、Orca の作業面は次のように整理できます。

出典: stablyai/orca README

向いているのは、複数ハーネスの結果を見比べる開発と、差分レビューをアプリ内で閉じたい開発です。
1 つのエディタで自分の打鍵が中心になる作業は、Orca の主目的から外れます。

特徴

• タスクごとに隔離した git worktree を持つため、並列エージェントが同じ作業ツリーを奪い合いません。
• エージェントのコンボボックスは、対応表にある CLI をワンクリックで起動します。表に無い CLI も、端末で動くプロセスとして起動できます。
• 状態表示は端末の OSC タイトルとエージェントフックから取ります。作業中、入力待ち、完了、失敗、アイドルをタブとサイドバーで共有します。
• 端末は分割と、再起動をまたぐ scrollback を備えます。実装は xterm.js の WebGL アドオンと node-pty です。
• worktree ごとに Chromium 窓を開けます。Design Mode は、クリックした要素の HTML、CSS、切り抜き画像をプロンプトへ添付します。
• 作成ダイアログは GitHub、Linear、Jira、GitLab の課題や PR を worktree に結び付けます。Bitbucket Cloud は Settings の認証と連携レビューの側にあり、作成時の課題リンク先には入っていません。
• CLI orca は、起動中のエディタに対して worktree 作成、端末送信、ブラウザ操作、成果物共有、スケジュール実行をスクリプト化します。
• モバイルコンパニオンは、稼働中のエージェント状態、利用量、アカウント切替、端末操作を手元から続けます。
• 実行先は Local、SSH ターゲット、Remote Orca Server、レシピ駆動の Cloud VM の 4 モードです。1 インストール内で混在できます。
• 匿名テレメトリは PostHog Cloud の米国リージョンへ送ります。DO_NOT_TRACK=1 または ORCA_TELEMETRY_DISABLED=1 で送信を止められます。
• Supported agents の表は 2026-10-03 時点で 37 行あります。Deep integration の注記があるのは Claude Code、Codex、Muse Code、Cursor CLI です。

出典: stablyai/orca README

出典: stablyai/orca README

出典: stablyai/orca README

新規起動の既定は、各 CLI の権限バイパスフラグを埋めた状態です。

Settings の Agent Permissions で、未カスタマイズのエージェントを Yolo と Manual の間でまとめて切り替えられます。
起動引数または環境の上書きが空でないエージェントは、その一括切り替えから外れます。

構造

システムコンテキスト図

利用者、Orca、Orca が所有しない外部システムの境界です。

コンテナ図

Orca の内側を、公式ドキュメントとリポジトリのトップレベル配置から切り出したコンテナです。

コンポーネント図

Main と実行先のモジュール境界です。
パスは 2026-10-03 の main ブランチに存在する名前です。

データ

概念モデル

Orca が扱う概念と、その利用関係です。
名前は公式ドキュメントの用語に合わせています。

情報モデル

属性は、公式ドキュメントと profile-state-storage-paths.ts に名前があるものに限っています。
SQLite の全カラムは含めていません。

永続化の置き場所は、実行形態によって次のように分かれます。

user-data-path.ts の initDataPath は、起動時に捕捉した userData 直下の orca-data.json というパスも組み立てます。
プロファイル索引が解決できるときは、profiles/<profileId>/ を読みます。
索引が無い CLI のフォールバックは、src/cli/handlers/agent-hooks.ts の legacyProfileStateLocation で、userData 直下の orca-data.json と profile-state.db です。
この 2 系統のパスについては、注意点でもう一度触れます。

構築方法

前提

• デスクトップで使うだけなら、配布物をインストールすれば足ります。
• main の開発ツリーを動かすには、package.json の engines.node が示す Node.js 24 と、packageManager の pnpm 12.8.1 が必要です。タグ v1.4.218 の packageManager は pnpm 12.0.0 です。
• エージェント CLI は Orca の外でインストールし、Orca が見る PATH に置きます。
• 遠隔で動かす場合は、そのマシンに git と、使うエージェント CLI の認証を置きます。ラップトップのログイン状態は自動では移りません。
• macOS の公開 cask は、macOS Big Sur 以降を depends_on に指定しています。

デスクトップの入手

安定版は GitHub Releases の latest から入手します。

# macOS Apple Silicon の安定版 DMG
curl -fL -o orca-macos-arm64.dmg \
  https://github.com/stablyai/orca/releases/latest/download/orca-macos-arm64.dmg

# Linux AppImage。GitHub のアセットは実行ビットを持たない
curl -fL -o orca-linux.AppImage \
  https://github.com/stablyai/orca/releases/latest/download/orca-linux.AppImage
chmod +x orca-linux.AppImage

Homebrew

macOS では公開 tap の cask を使えます。
2026-10-03 時点の tap の version は 1.4.218 で、同日の latest Release と一致しています。

brew install --cask stablyai/orca/orca

cask は auto_updates true です。
アプリ内の electron-updater が /Applications の Orca.app を差し替えます。
そのため brew upgrade は --greedy を付けない限り更新を取り合わない、と cask のコメントが説明しています。
cask は Orca.app と、アプリ内の Contents/Resources/bin/orca を PATH へ出します。

Linux のコマンド名

Linux のパッケージ名と CLI 名は orca-ide です。
GNOME のスクリーンリーダーが /usr/bin/orca を既に使っているため、その名前を避けています。

• .deb と .rpm は、インストール時に /usr/bin/orca-ide を PATH に置きます。
• AppImage は、Settings → General → Orca CLI から ~/.local/bin/orca-ide を登録します。
• Orca が管理する端末の中では、シムにより orca で呼べます。
• ヘッドレスの orca serve は、起動の途中で ~/.local/bin/orca を書くことがあります。最初の起動コマンドは orca-ide serve です。

# スクリーンリーダーと衝突しないことの確認
command -v orca-ide
orca-ide status --json

スクリーンリーダーを使わない環境で、自分のシェルでも短い名前を使いたい場合の公式例は次のとおりです。

ln -s "$(command -v orca-ide)" ~/.local/bin/orca

初回起動

初回起動で Orca は次を行います。

• リポジトリ追加のため、ホームディレクトリへのアクセスを求めます。
• ~/.claude、~/.codex、Ghostty の端末設定があれば、取り込みを提案します。
• 空のランディング画面から、最初のリポジトリを追加します。

自動更新の既定は stable チャネルです。
RC を恒久的に選ぶスイッチはありません。
Check for Updates を修飾キー付きでクリックすると、その回だけ prerelease を含めます。

Linux の AppImage は、アプリが更新をその場で適用します。
.deb と .rpm は、ダウンロード後に絶対パスへ解決したインストールコマンドをコピーさせます。
実行前に Orca を終了します。
Orca 自身は root へ昇格しません。

/usr/bin/sudo /usr/bin/apt install -- '/home/you/.cache/orca-updater/pending/orca-ide_1.4.194_amd64.deb'

上のパスは、Install ドキュメントが示す形の例です。
版番号とホームディレクトリは、そのマシンの Copy Install Command が単一引用符で埋めた値を使います。

開発ツリー

main の package.json は、デスクトップの入口を ./out/main/index.js、CLI を ./out/cli/index.js と宣言しています。
開発用の起動スクリプトは pnpm run dev です。
Electron ランタイムを確保してから electron-vite を起動します。
開発依存の Electron は、main とタグ v1.4.218 の package.json がどちらも 43.7.5 です。

pnpm install --frozen-lockfile --cpu=current,x64,arm64
pnpm run dev

利用方法

CLI の主なパラメータを、個別の例より先にまとめます。
コマンド名は、macOS と Windows、および Orca 管理端末の中では orca、Linux の自分のシェルでは orca-ide です。

出典: stablyai/orca README

リポジトリと worktree

登録、参照、作成、一覧、削除の公式例です。

orca repo add --path /absolute/path/to/repo --json
orca repo list --json
orca repo show --repo id:repoId --json
orca worktree create --repo id:repoId --name review-api --agent claude --setup run --json
orca worktree ps --json
orca worktree rm --worktree id:worktreeId --force --json

作成ダイアログを閉じても、git fetch と git worktree add はバックグラウンドで続きます。
失敗するとタブ内のパネルにエラーと Retry が出ます。
削除は、確認のうえでディレクトリとブランチの両方を外します。
未マージの可能性があるブランチを git が残した場合は、残ったブランチのレビューに案内されます。

Orca の外で git worktree add したディレクトリは、最初はサイドバーに出ません。
隠れた worktree のカードから Non-Orca worktrees を開き、Show で取り込みます。

エージェントの起動

コンボボックスから起動すると、Orca がその CLI を worktree の端末で起動します。
状態は OSC タイトルとフックで更新され、作業中からアイドルへ移ると完了通知を出せます。
プロセスが終わると Restart チップが出ます。
Codex の Restart は、その時点のアカウントを保ちます。

端末でバイナリを手打ちしたセッションは、Orca が認識するエージェントにならないことがあります。
状態インジケータが必要なセッションは、コンボボックスから起動します。

権限を戻すには、Settings → Agents → Agent Permissions で Manual を選ぶか、そのエージェントの起動引数または環境を明示して上書きします。
空でないカスタム値を入れたエージェントは、その後の権限モードの一括切り替えから外れます。

エージェントに Orca CLI のスキルを入れる方法は次のとおりです。

npx skills add https://github.com/stablyai/orca --skill orca-cli
orca skills install --skill orca-cli

端末、ファイル、ブラウザ

端末への送信と待機、ファイルをタブで開く公式例です。

orca terminal list --json
orca terminal send --text "continue" --enter --json
orca terminal wait --for tui-idle --timeout-ms 30000 --json
orca file open src/App.tsx
orca file diff src/App.tsx --staged

ブラウザは、開いているタブに対する snapshot と操作の繰り返しです。
タブが無いと browser_no_tab になります。

orca tab create --url https://example.com
orca goto --url https://example.com --json
orca snapshot --json
orca click --element @e3 --json
orca fill --element @e1 --value "user@example.com" --json

iOS Simulator のブリッジは、アクティブな worktree にスコープされます。

orca emulator list --json
orca emulator attach "iPhone 16" --json
orca emulator tap 0.5 0.7 --json

デバイス名は orca emulator list が返す値を使います。
上の iPhone 16 は引数の形を示す例です。

orca.yaml と .worktreeinclude

新しい worktree はクリーンなチェックアウトです。
git 無視の依存や秘密情報は、次の 3 つの経路で補います。

# orca.yaml
worktree:
  sharedDirectories:
    - node_modules
    - .cache

# .worktreeinclude
.env
.env.local
.vscode/settings.json

sharedDirectories の各エントリは、primary checkout にディレクトリとして存在し、かつ git 無視である必要があります。
追跡されているパスや欠落パスはスキップされます。
.worktreeinclude は、glob や否定を使わないリテラルパスだけをコピーします。

Cloud VM のレシピは、primary checkout の orca.yaml に environmentRecipes があるときに作成 UI へ出ます。
機能ブランチだけにレシピを書いても、作成一覧には載りません。
doctor と試行の provision は、作業中のブランチから実行できます。

リモートの接続

SSH worktree は、Settings の SSH にホストを追加し、作成時の Run on でそのホストを選びます。
ランタイムの所有者はラップトップ側の Orca です。

出典: stablyai/orca README

Remote Orca Server は、サーバ側がプロジェクトとセッションを所有します。
デスクトップ同士なら Tailscale で接続し、サーバ側で Settings → Remote Orca Servers → Advertise this app as a server → New Link とたどってアクセスリンクを作ります。
クライアントはそのリンクを Add Server に貼ります。

ヘッドレスで起動する場合は次の形です。
Linux では orca-ide を使います。

orca-ide serve --pairing-address 100.64.1.20
orca-ide serve --port 6768 --pairing-address 100.64.1.20
orca-ide serve --pairing-address 100.64.1.20 --mobile-pairing

100.64.1.20 と 6768 はドキュメントの例です。
到達できる Tailscale アドレスと、ファイアウォールが許すポートに置き換えます。
同じマシンの同じ共有セットアップでは、デスクトップの共有と orca serve を同時に起動できません。
orcad 同士の二重起動は、別の拒否コード orcad_instance_lock_held で止まります。

ヘッドレスでアカウントとスキルを登録する公式例です。

orca account add --agent claude
orca account add --agent codex
orca skills install --skill orca-cli --skill orchestration

モバイル

iOS は App Store の Orca IDE です。
Android は、ホームページと README が指す APK mobile-android-v0.0.50 です。
ペアリング後は、エージェントの完了通知、利用量、端末へのフォローアップを電話から続けられます。
ヘッドレスの場合は、--mobile-pairing が表示する QR またはリンクを、同じ tailnet 上の電話で読み取ります。

出典: stablyai/orca README

運用

チャネルと更新

• 既定の更新チャネルは stable です。RC は修飾キー付きクリックか、Releases からの直接ダウンロードで入れます。
• 古いビルドへ戻しても、Orca は worktree データを強制的にダウングレードしない、と Install ドキュメントが述べています。
• AppImage は終了せずに置き換えます。.deb と .rpm は終了してから、コピーしたコマンドを実行します。
• AUR や Nix のように Orca が更新を駆動できないパッケージでは、ダウンロードを提案せず、新しい版の存在だけを知らせます。
• 署名付き apt / yum リポジトリは、ドキュメントが Issue #18086 として未実施の計画に挙げています。

ログと診断

• Help → Open Logs でログディレクトリを開きます。
• Help → Send Feedback は画面キャプチャを添付できます。再現が難しい不具合ではログも添えます。
• エージェントの生のエラー文はテレメトリへ出ません。ローカルの診断トレースに残り、診断バンドルを明示的に共有したときだけ Orca 側へ届きます。
• テレメトリを止める環境変数は、その起動の送信だけを止めます。外すと、次回起動で保存済みの設定に戻ります。

Orca を起動するシェルで export してから起動します。

export DO_NOT_TRACK=1

export ORCA_TELEMETRY_DISABLED=1

アプリ内で Settings → Privacy の Share anonymous usage data を切ると、その設定は保存されて以降も続きます。
送信先は PostHog Cloud の米国リージョンです。
保持期間は PostHog のプラン既定で、Orca は独自の保持期間を設定していないと書いています。

テレメトリが送るもの

イベントに付くのは、Orca の版、OS、CPU アーキテクチャ、粗い OS リリース、stable または rc、ローカルのランダム ID です。
ホスト名、ユーザ名、IP は送りません。
国が、リクエストから導く唯一の地理情報です。

リモートの生存

• Remote Orca Server は beta です。ドキュメントは、Tailscale の tailnet や LAN など、利用者が制御する私設経路に限るよう求めています。
• ペアリング URL はパスワードと同じ扱いです。誤って渡した grant は Shared Server Access から破棄すると、そのクライアントは直ちに切断されます。
• 未使用のリンクを再生成すると、前の未使用リンクは置き換わります。既にペアリング済みの grant は、破棄するまで残ります。
• ポートを公衆インターネットへ直接公開しない、と Access and security が書いています。
• サーバとクライアントのプロトコルが合わないときは、両方の Orca を更新します。
• エージェント CLI が見つからないときは、サーバ側の PATH、ホーム、認証を直します。クライアント側の環境は使われません。

orcad は data root の orcad.lock を取ってから、プロファイル索引に触れます。
拒否コードは次のとおりです。

所有者が自分で権限が緩いだけの root は、0700 に締めます。
資格情報を OS キーリング無しで置くためです。
Windows は所有者と mode の検査を免除しています。

スキルとフック

• orca skills update --all は、Settings UI が無いホストでスキルを更新します。
• エージェント状態フックは orca agent hooks on、off、status で切り替えます。アプリの再起動なしで反映される、と Settings ドキュメントが書いています。
• Keep computer awake は On、Agent、Off の 3 段階です。デスクトップのステータスバーでは Caffeinate と表示されます。ペアリングした Web クライアントでは表示されません。

orca agent hooks status
orca skills update --all

容量とアイドル

• 使っていない worktree は閉じます。worktree ごとにファイルウォッチャが残るためです。
• 多数のブラウザタブを持つ分割レイアウトが、公式トラブルシューティングが挙げる最大の RAM 要因です。
• Resource Manager の Clean up workspaces は、ローカル、main、フォルダ workspace、切断中の SSH ホスト上の workspace を横断し、サイズと Git 状態を見せてから削除します。
• Agent Dashboard は Experimental です。列は Needs You、Working、Done です。Idle は、約 30 分完了報告が無いセッションを指し、ボード設定で表示できます。
• サイドバーの Sleep は、生きている端末やブラウザがある workspace のパネルを閉じます。子孫つきの Sleep は、同じプロジェクト、リポジトリ、ホストの検証済みの子に限られます。

ベストプラクティス

worktree をサンドボックスの代わりにしない

Supported agents は、worktree は隔離されたチェックアウトであり、セキュリティサンドボックスではないと書いています。
エージェントは、そのプロセスから見えるファイルとネットワークへ届きます。
信頼していないタスクでは、Agent Permissions を Manual にします。
Yolo のまま使うのは、その worktree の権限境界を自分で把握しているときだけにします。

依存の共有と秘密のコピーを分ける

node_modules や .cache のような、再生成できる大きいディレクトリは worktree.sharedDirectories に置きます。
.env のように worktree ごとに独立させたいファイルは .worktreeinclude でコピーします。
共有済みのパスは .worktreeinclude から再コピーされません。
レシピや共有ディレクトリの正本は primary checkout に置きます。

実行モードを所有境界で選ぶ

1 つのインストールで、これらを worktree ごとに混ぜられます。

遠隔の認証をサーバ側で完結させる

Remote Orca Server と orca serve では、Claude、Codex、git、gh をサーバマシンにインストールします。
ヘッドレスではクライアントから Add account が使えないため、orca account add をサーバのシェルで実行します。
ペアリングリンクは私設経路でのみ渡し、不要な grant は破棄します。

GitHub の枠を CLI で確認する

PR チェックが止まったときは、Settings の GitHub API Budget だけを見ずに、ローカルの gh で枠と認証を確認します。

gh auth status -h github.com
gh api user
gh api rate_limit --jq '.resources.core'

予算表示に余裕があっても、REST が別の枠で止まっていることがあります。
切り分けは公式の GitHub errors ページに続きます。

Linux ではコマンド名を固定する

自分のシェルとスクリプトでは orca-ide を呼びます。
GNOME 環境では、command -v orca がスクリーンリーダーを指すことがあります。
シムの orca は、Orca 管理端末の中でエージェントに使わせるだけにします。

注意点

ドキュメントと実装の乖離

資料間の食い違い

2026-10-03 時点の未確認事項

トラブルシューティング

公式の Troubleshooting、Remote Orca Servers、Install、Supported agents に症状として書かれているものを載せます。

エージェントと差分

• エージェント単体が Orca の外でも失敗するなら、Orca の不具合として扱う前に、その CLI の認証を直します。
• Restart は、同じ作業ディレクトリで同じエージェントを起動し直します。

worktree 作成

• 作成中でも、他の worktree へ切り替えられます。進行状況はサイドバーとタブに出ます。
• CLI で git worktree remove した場合、Orca は次のリフレッシュで自分の状態を片付けます。

CLI とブラウザ

• Linux で command -v orca が成功しても、それはスクリーンリーダーの可能性があります。
• ブラウザ操作の @e1 のような参照は、直前の orca snapshot が返した値だけを使います。

SSH とリモート

• デスクトップが既にそのマシンを共有しているときは、同じセットアップで 2 つ目の orca serve を起動しません。
• アクセスリンクを誤って配ったら、未使用リンクの再生成ではなく、既存 grant の破棄を先に行います。

GitHub と連携の枠

• 認証の本体はローカルの gh です。Orca の表示が新しくても、gh のトークンが無効ならパネルは失敗します。
• 不具合報告の公式窓口は GitHub Issues と Discord です。

まとめ

• Orca は、利用者が持ち込む CLI エージェントを、タスクごとの git worktree・端末・ブラウザに割り当てて並列に走らせる ADE です。
• 内部は Electron の Renderer / Preload / Main と、CLI、ヘッドレス監督の orcad、端末デーモン、Relay で構成されます。状態はプロファイル単位の orca-data.json と profile-state.db に置かれます。
• 実行先は Local、SSH worktree、Remote Orca Server、Cloud VM レシピの 4 モードで、ランタイムの所有者で選び分けます。
• 依存は orca.yaml の sharedDirectories で共有し、秘密ファイルは .worktreeinclude でコピーします。
• 新規起動の既定は権限バイパスで、worktree はセキュリティサンドボックスではありません。信頼できないタスクでは Manual に切り替えます。
• Linux では orca-ide を使い、版の確認は Release と公開 tap で行います。

この記事が少しでも参考になった、あるいは改善点などがあれば、ぜひリアクションやコメント、SNSでのシェアをいただけると励みになります！

参考リンク

公式ドキュメント

• What is Orca?
• Install
• Ways to run Orca
• Worktrees
• Agents and sessions
• Supported agents
• Orca CLI overview
• Remote Orca Servers
• Settings reference
• Privacy and Telemetry
• Troubleshooting
• ホームページ

リポジトリの一次ファイル

• stablyai/orca
• LICENSE
• package.json
• profile-state-storage-paths.ts
• profile-state-active-location.ts
• user-data-path.ts
• orcad-operations.md
• アプリリポジトリ内の Casks/orca.rb
• 公開 tap の Casks/orca.rb
• Releases
• Issue 18086

配布とコンパニオン

• iOS App Store
• Android APK 0.0.50
• Discord