Orcaのハマりどころ ― ワークツリーの容量対策から、Design Modeで画面を指さして直させるまで

Orca は、Claude Code や Codex などのCLIエージェントを、タスクごとに別々の git worktree で並べて動かすためのデスクトップアプリです。開発元の stablyai はこれを ADE（Agent Development Environment）と呼んでいて、MIT ライセンスで macOS・Windows・Linux 向けに配られています。モデルの利用料は含まれず、手元の Claude Code や Codex の契約をそのまま使います。

ボタン一つで作業用のブランチとフォルダができるので、気軽にタスクを増やせます。ところが、気軽に増やした結果としてディスクが埋まる、ワークスペースとワークツリーの区別がつかない、エージェントの状態表示が出たり出なかったりする、といったところでつまずきやすい道具でもあります。この記事では、そうしたつまずきどころを順に見たあと、いちばん便利だと感じている内蔵ブラウザの Design Mode、つまり画面の要素を指さしてエージェントに直しを頼む機能を、実際の画面で説明します。

※2026年10月30日時点の公式ドキュメント（onorca.dev/docs）と GitHub のソースコードで確かめた内容です。Orca は更新が速く、設定の名前や場所は変わることがあります。

ワークツリーを作るほどディスクが減る

最初に当たりやすいのがディスク容量です。Orca はタスクごとに git worktree でリポジトリの作業コピーを作ります。作業が終わってもPRがマージされても、そのワークツリーは自動では消えません。公式ドキュメントにも自動で片付ける機能の説明はなく、削除はサイドバーの右クリックメニューか、Resource Manager の「Clean up workspaces」から人が行う作りです。エージェントがまだ動いているかもしれないフォルダや、コミットしていない変更を勝手に消さないための設計だと受け取っています。

容量を食うのはソースコードそのものではありません。新しいワークツリーはクリーンなチェックアウトなので、.gitignore されている node_modules や .next のようなビルドキャッシュは入っていません。そこで毎回 npm install やビルドを走らせると、その分がワークツリーの数だけ積み上がります。仮に依存パッケージとキャッシュで2GBのプロジェクトなら、30個で60GBです（数字は説明用の試算です）。

消すときに知っておくこと

• Orca からワークツリーを削除すると、フォルダとブランチの両方が消えます。確認ダイアログが出ます。
• マージされていないコミットがありそうなブランチは「preserved branch」として残され、あとで確認できます。
• Resource Manager の「Clean up workspaces」では、各ワークスペースの状態・サイズ・Gitの状態を見てから選んで消せます。大きいものから片付けるならここが早いです。
• ターミナルで git worktree remove した場合も、Orca は次にそのリポジトリを読み直したときに自分の状態を整理します。

使っていないワークツリーは、開いているだけでもファイル監視が動き続けます。トラブルシューティングのページでも、使わないワークツリーは閉じるよう書かれています。容量だけでなく、動作の重さにも効いてきます。

そもそも容量を食わせない

消すより効くのは、ワークツリーごとに重いフォルダを持たせないことです。Orca には、gitignore されたファイルやフォルダを新しいワークツリーへ持ち込む仕組みが3つあります。

orca.yaml では、ワークツリー作成時に走らせるセットアップスクリプトと、削除の前に走らせるスクリプトも書けます。公式ドキュメントの例はこうです。

scripts:
  setup: |
    pnpm install
  archive: |
    echo Workspace archived
setupAgentStartupPolicy: wait-for-setup
defaultTabs:
  - title: Agent
  - title: Git status
    command: git status --short
worktree:
  sharedDirectories:
    - .cache

※公式ドキュメント「orca.yaml & .worktreeinclude」の例をそのまま載せています。わたしの環境で動かした設定ではありません。

共有するフォルダは、メインのチェックアウトに実在し、gitignore されている必要があります。setupAgentStartupPolicy: wait-for-setup にすると、セットアップが終わってからエージェントが起動します。依存パッケージが入る前にエージェントがテストを走らせて失敗する、という順番の問題を避けられます。

この例がセットアップに pnpm install を使っているのは理にかなっています。pnpm はパッケージの実体を1か所のストアに置き、各プロジェクトの node_modules からはハードリンクで参照します。ワークツリーを増やしても、パッケージの実体は増えません。npm のままワークツリーを量産するのが、いちばん容量を食う組み合わせです。

逆に node_modules そのものをシンボリックリンクで全ワークツリーに共有するのは、ブランチによって依存が違うと壊れます。依存を変えるタスクを並べるなら、共有より pnpm のほうが安全です。

定期的な掃除を自動にしたいなら、Orca の Automations（スケジュールで実行するプロンプト。orca automations コマンドかデスクトップの Automations 画面で作る）に「マージ済みのブランチのワークツリーを一覧にして消して」と頼む手もあります。ただしこれは Orca の機能としての掃除ではなく、エージェントに頼む作業です。わたしは試していないので、まず --disabled で作って手で実行し、消える対象を確かめてから定期実行にするのが無難です。

ワークスペースとワークツリーは別のもの

Orca の画面で「New Workspace」を作ると、裏でワークツリーも作られます。いつも1対1なので同じものに見えますが、層が違います。

• ワークツリーは Git の仕組みで、ディスク上のフォルダそのものです。中で cd して普通に git を使えます。
• ワークスペースは Orca のサイドバーに並ぶ作業単位です。中身はワークツリーのこともあれば、メインのチェックアウトや、Git のワークツリーを作らずに既存フォルダを開く「フォルダワークスペース」のこともあります。ワークスペースには、エージェントのターミナル、タブやペインの配置、ワークツリー専用のブラウザ、ひも付けた PR や Issue がまとまっています。

容量やファイルの話ならワークツリー、画面の切り替えやタスクの話ならワークスペース、と分けて考えると混乱しません。

サイドバーに出てこないワークツリーもあります。Orca の外、たとえば普通のターミナルで git worktree add したものは、Orca が見つけても「外部のワークツリー」のまま隠しておき、表示を選んだものだけがサイドバーに並びます。

Claude Code が自分で作るワークツリーなどをサイドバーに出すかどうかの既定は Settings → General → Workspace で決められ、プロジェクトごとに上書きもできます。

エージェントの状態はどう読み取っているのか

Orca のタブには、エージェントが作業中か、入力待ちか、終わったかが印で出ます。最近は Zed エディタなどが ACP（Agent Client Protocol）という、エディタとエージェントをつなぐ専用のやり取りを使い始めているので、Orca もそうだと思うかもしれません。公式ドキュメントには ACP の記述は見当たらず、ターミナルで動かすエージェントについては、実際の仮想端末の上でCLIをそのまま動かしています。エージェントから見ると、人がターミナルで起動したのと同じ状態です。だから Orca はエージェントの選択肢に40種ほどを最初から並べられますし、ここにないCLIでもターミナルで動くものは動かせます。

状態は、公式ドキュメントによると次の2つで判定しています。

• ターミナルのタイトルを変える OSC シーケンス。OSC は端末に送る制御用の文字列で、ウィンドウのタイトルを変えるのにも使われます。Claude Code を Orca から起動すると、この OSC でタイトルを書き換えるステータスラインのフックが一緒に仕込まれます。
• エージェントのフック。Claude Code の .claude/ や Codex の .codex/ に、作業中・入力待ち・完了を Orca へ知らせるフックを入れます。Settings → Agents → Agent status hooks で入り切りでき、orca agent hooks status で状態を見られます。

画面からエージェントへ渡すものも、特別な通信ではありません。たとえばクリップボードの画像を貼ると、Orca はそれを一時ファイルに保存し、そのパスをターミナルに打ち込みます。ソースコードにも「パスはターミナルに入力されるので、シェルが展開する文字を残さない」という趣旨のコメントがありました。

※Orca にはこれとは別に、エージェントを構造化されたチャット画面で開く「Chat UI」（Settings → Chat → Providers）もあります。ここで書いたのはターミナルで動かす場合の話です。

ワークスペースを開いたら Claude Code が立ち上がるようにする

状態の印が出ないとき、よくある原因は起動のしかたです。ワークスペースの素のシェルに自分で claude と打って起動すると、Orca のフックを通らないことがあります。公式ドキュメントのトラブル対応にも、印が出ないなら手でコマンドを打たずにエージェントの選択欄から起動するように、と書かれています。

毎回選ぶのが面倒なら、既定のエージェントを決めておきます。

1. Settings を開く
2. Agents を開く
3. Default Agent で Claude Code を選ぶ（PATH から見つかったエージェントが並びます）

これで新しいワークスペースを作ると、最初から Claude Code が起動した状態で始まります。前からあるワークスペースは前回のタブが戻るので、素のシェルのタブが残っているならタブの「+」から Claude Code を開き直し、古いタブを閉じておきます。

.zshrc や .bashrc の末尾に claude と書いて自動起動させる方法は勧めません。シェルを開くたびに起動してしまううえ、Orca のフックも通りません。

もう一つ気をつけたいのが権限です。Orca はエージェントを起動するとき、既定で全自動の権限フラグを付けます。Claude Code なら --dangerously-skip-permissions です。ワークツリーで隔離されているとはいえ、エージェントはコマンドを確認なしで実行します。気になる場合は Settings → Agents でエージェントごとの起動引数を変えられます。

Design Mode で、画面を指さして直させる

Orca には Chromium ベースのブラウザが入っていて、ワークツリーごとに別のブラウザを持てます。ローカルで動かしている開発サーバーを見るだけでも便利ですが、本領は Design Mode です。

画面の修正をエージェントに頼むとき、「ヘッダーの右から2番目のボタンの余白を」と言葉で説明するのは手間がかかります。クラス名を調べたり、スクリーンショットを撮って貼ったりもしがちです。Design Mode なら、直したい要素をブラウザ上でクリックして、そこにメモを書けば済みます。

手順は次のとおりです。

1. 内蔵ブラウザのツールバーで Design Mode のトグルをオンにします。カーソルが要素の選択に変わり、マウスを乗せた要素が枠で強調されます。
2. 直したい要素をクリックします。上の画面では、副業サービスの比較サイトの見出しを選びました。要素の上に h1 と、見出しの文言、880×149 という大きさが出ています。
3. 出てきたメモ欄に、頼みたいことを書きます。画面では「ここ一列になる？」と書きました。メモ欄の下には「変更」と「質問」のボタンがあり、直してほしいのか、まず聞きたいのかを選べます。
4. 「追加」（Ctrl + Enter）でメモを確定します。

クリックした要素について、Orca は次の情報を集めてエージェントのターミナルに添付として渡します。

• 要素の HTML（要素そのものと、周りの少し広い範囲）
• 計算済みの CSS（色、フォント、余白など、実際に効いている値）
• その要素だけを切り抜いたスクリーンショット
• ソースファイル上の位置（開発モードのソースマップがある場合だけ）

どの要素の話か、今どう見えているかを、エージェントは最初から受け取れます。言葉だけで場所を説明するより、取り違えが減ります。

メモは1つずつ送るだけでなく、注釈トレイに何件かためてからまとめて送れます。「ここは1行に」「ここは余白を広げて」と画面を見ながら順にメモしていき、最後に一度で渡す使い方です。送ったメモはトレイから消え、送っている最中に足したメモは残ります。エージェントがソースを直すと開発サーバーが再読み込みし、同じ要素をもう一度クリックして確かめる、という流れで回ります。

この機能を手早く呼び出したいなら、Settings → Shortcuts の「Annotate page element」にキーを割り当てておけます。

エージェントにブラウザを操作させる

逆向きの使い方もできます。Orca のターミナルでは orca コマンド（Linux では GNOME のスクリーンリーダー Orca と名前がぶつからないよう orca-ide）が PATH の先頭に入っていて、エージェントがこれで内蔵ブラウザを操作できます。

orca goto --url http://localhost:3000
orca snapshot --json          # 画面の要素に @e1, @e3 のような参照を付けて返す
orca click --element @e3
orca fill --element @e1 --value "test@example.com"
orca screenshot --json

※公式ドキュメント「Orca CLI overview」の流れに沿った例です。URL と入力値は説明用の値です。

エージェントがコードを直し、自分でブラウザを開いて表示を確かめ、崩れていればまた直す。その様子を隣のペインで見ていられます。エージェントにこのコマンドの使い方を覚えさせるには、orca skills install --skill orca-cli で専用のスキルを入れます。

ブラウザ側にも、並行作業で効く機能があります。

• タブとスクロール位置はワークツリーごとに保存され、別の作業から戻ると元の画面に戻ります。
• タブごとに表示サイズを指定できます。Chrome DevTools Protocol の端末エミュレーションを使うので、ページ側の window.innerWidth やメディアクエリもその幅で動きます。スマートフォン幅でだけ崩れる要素を Design Mode で選んで直させる、という使い方ができます。
• Browser-use profiles で、ログイン状態、Cookie、ユーザーエージェントを分けたブラウザを使えます。管理者と一般ユーザーの画面を見比べるときに便利です。

最初に押さえておくこと

• ワークツリーは自動では消えない。終わったら右クリックか Resource Manager の「Clean up workspaces」で消す。
• 容量を食うのは node_modules やビルドキャッシュ。pnpm を使い、orca.yaml の sharedDirectories や Settings の Shared Paths で、作り直せる大きなフォルダを共有する。
• エージェントは選択欄から起動するか、Default Agent を決めておく。素のシェルで手打ちすると状態の印が出ないことがある。既定で全自動の権限フラグが付く点も確かめておく。
• 画面の修正は Design Mode で要素を選んでメモを書く。HTML・CSS・切り抜き画像がまとめてエージェントに渡る。

確認した資料

• stablyai/orca（GitHub） — 概要、ライセンス、対応OS。Default Agent の設定画面（AgentDefaultSetting.tsx）とクリップボード画像の扱い（clipboard-image-temp-file.ts）をソースで確認。
• Worktrees — 削除の挙動、外部ワークツリー、共有パス。
• orca.yaml & .worktreeinclude（リポジトリ内のドキュメント原稿） — orca.yaml の例とキー。
• Agents & sessions、Claude Code in Orca、Agent hooks & memory — 状態の判定、起動時の権限フラグ。
• Design Mode、Per-worktree browser — 送られる情報、注釈トレイ、表示サイズ。
• Orca CLI overview、Scheduled automations、Install — ブラウザ操作のコマンド、Automations、Linux のコマンド名。

いずれも2026年10月30日に確認。