Roola
yahir0/Roola
Explorador de arquivos com terminal, Git e integração Claude Code
Ver no GitHubExplorador de arquivos para desenvolvedores em Windows/macOS que integra terminal, execução de comandos e skills do Claude Code em uma interface unificada. Permite criar atalhos para pares "diretório + ação" frequentes e acessá-los com um clique, com visualização de código, Git integrado e notificações nativas.
Instalação
npx convez-ai yahir0/Roola1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Navegar projetos e abrir terminais contextualizados por diretório
- Executar commands e skills do Claude Code diretamente do filesystem
- Visualizar código, diffs e histórico Git em abas do workspace
- Gerenciar múltiplos projetos com atalhos salvos e notificações de tarefas
Veredito

Roola é uma ferramenta madura e bem polida que elimina contexto-switching entre explorador, terminal e editor para desenvolvedores. A integração nativa com Claude Code e o design focado em eficiência (teclado-driven, notificações zero-config) o tornam valioso para fluxos de desenvolvimento iterativo, mas requer macOS 14+ ou Windows 10/11.
README
A tradução para o português deste README ainda está na fila.
Compatible with Claude Code — インストール済みなら Skill 実行・対話セッション起動などの統合 UI が自動で有効化されます。インストールされていなくても汎用ランチャーとして動きます(ADR-0016 / ADR-0022)。

Overview (English)
Roola is a file explorer built for developers on macOS and Windows. Browse your filesystem and reach your destinations instantly — open a shell, run an arbitrary command, or launch a Claude Code skill with one click, all scoped to a directory and running inside a built-in PTY terminal. Register frequently-used "directory + action" pairs once, then launch them from the sidebar.
Highlights
- 3-pane tabbed workspace — Explorer / Terminal / Git tabs, freely arranged across three panes. Per-tab state, layout restored on relaunch.
- One-click launchers — open a shell, run an arbitrary command, or invoke a Claude Code skill, all scoped to a chosen directory. Group launchers into folders.
- Built-in PTY terminal — SwiftTerm on macOS; xterm.js (WebView2) on Windows.
Shift+Enterinputs a literal newline for multi-line prompts. - Built-in Git view — diff / history / branches / stash, as a workspace tab.
- Read-only file preview — select a file to preview it in a side pane: syntax-highlighted code, images, or PDF. Hidden by default; opens automatically for previewable files.
- Keyboard-driven explorer — arrow keys to move the selection,
Enterto open,→/←to descend / go up. - Floating notepad, CPU/memory monitor, customizable keybindings, multi-window.
- Task notifications, zero-config — Roola panes relay terminal notification
escape sequences (OSC 9/777) to system notifications (ADR-0066). No hooks, no
setup: Claude Code notifies instantly when it needs permission, and ~60s after
finishing a turn while waiting for input. Any CLI tool can notify with a single
printf. Click a notification to jump back to its pane. macOS uses Notification Center; Windows uses toast notifications. - Polaris design system — dark-only, single accent (warm gold or ice blue), function-first aesthetic. No light theme.
- Optional Claude Code integration — when Claude Code
is installed, Roola auto-enables skill detection, one-click skill launch, and a
claude --versionhealthcheck banner. Roola is not an official Claude / Anthropic product.
Install
macOS: Download the latest signed & notarized DMG from the
Releases page, drag Roola.app into
Applications, and launch from Launchpad or Spotlight. Auto-update via
Sparkle. Requires macOS 14 (Sonoma) or later
(Apple Silicon & Intel).
Windows: Download RoolaSetup-x.x.x.exe from the
Releases page and run the installer.
Auto-update via WinSparkle. Requires Windows 10/11
(64-bit).
License: MIT.
The detailed documentation below is in Japanese. For architecture notes and design decisions in English-readable form, see
docs/(mixed JP/EN).
Quick Start
macOS:
- DMG をダウンロード: Releases ページから最新版を取得(公証 + ステープリング済み)。
- インストール: DMG を開いて
Roola.appをApplicationsフォルダにドラッグ。 - 起動: Launchpad もしくは Spotlight から
Roolaで起動。
Windows:
- インストーラをダウンロード: Releases ページから
RoolaSetup-x.x.x.exeを取得。 - インストール: インストーラを実行してウィザードに従う。
- 起動: スタートメニューまたはデスクトップショートカットから起動。
自分でビルドしたい場合は Build from source を参照。
主な機能
- 3 ペインタブ式ワークスペース — Explorer / Terminal / Git の 3 タイプのタブを 3 ペインに自由配置(ADR-0026)。タブ単位で per-tab 状態を保持し、再起動でレイアウトを復元(ADR-0028)。
- ファイルエクスプローラ — ローカルディレクトリをブラウズ、ダブルクリックで遷移、十字キー / Enter でも操作(ADR-0051)、お気に入り・Cmd+C でパスコピー(ADR-0021)。
.claude/skills/を検知して特別アイコン化。 - ファイルプレビュー — ファイルを選択すると右ペインに読み取り専用プレビューを表示。コード(シンタックスハイライト)/ 画像 / PDF に対応(ADR-0046 / 0050)。既定は非表示で、プレビュー可能なファイルの選択で自動的に開閉する。
- ワンクリック・ランチャー — 「ディレクトリ + 動作」を登録し、サイドバーからワンタップで起動。フォルダで 1 階層グルーピング可(ADR-0019 / 0029)。
- アプリ内 PTY ターミナル — SwiftTerm ネイティブビューによる高速描画(ADR-0031)。Shift+Enter で改行入力(ADR-0032)。
- Git ビュー — Diff / コミット履歴 / ブランチ操作・stash をワークスペースタブとして提供(ADR-0030)。
- ノートパッド — ワークスペース外のフローティングパネル。トップバーのメモアイコンから開閉(ADR-0036)。
- アクティビティモニタ — トップバーに CPU / メモリの占有率をミニゲージ表示。クリックで上位プロセス一覧(ADR-0039)。
- カスタマイズ可能なキーボードショートカット — コマンドレジストリ + ネイティブメニューバーによる統一機構(ADR-0033)。
- 多言語化 — 日本語 / 英語(Flutter 公式 gen-l10n、ADR-0034)。
- Polaris デザインシステム — ダーク専用・機能主義のオリジナルデザイン(ADR-0038)。アクセント色は暖色ゴールド / アイスブルーの 2 択。
- 外観モード — 透過 / 不透明 の 2 モードを切替。
- マルチウィンドウ — メニューバー「ファイル → 新規ウィンドウ」または Dock 右クリックから別プロセスを起動(ADR-0012)。
- Compatible with Claude Code — インストール時に Skill 検出・対話セッション起動・ヘルスチェック等の統合 UI が有効化(詳細)。
- タスク通知(設定ゼロ) — ペイン内の CLI ツールが出す通知エスケープシーケンス(OSC 9/777)を OS 通知に中継(ADR-0066)。フック登録も設定も不要で、Claude Code の許可待ちは即時、ターン完了後の入力待ちは約 60 秒で通知。通知クリックで該当ペインへフォーカス復帰。
動作環境
| プラットフォーム | 要件 |
|---|---|
| macOS | macOS 14(Sonoma)以降(Apple Silicon / Intel) |
| Windows | Windows 10 / 11(64-bit) |
- Claude Code CLI は オプション(公式ガイド)
Build from source
開発 / カスタムビルド用。配布版を使うだけなら不要です。
macOS:
# 初回セットアップ(pub get + build_runner でコード生成)
make setup
# 起動(Debug ビルド、bundle ID は dev.tech.yahiro.Roola)
make run
# 配布用 DMG をビルド(要: Developer ID Application 証明書 + notarytool プロファイル)
make dist SIGN_IDENTITY="Developer ID Application: NAME (TEAMID)" \
NOTARY_PROFILE=your-notary-profile
FVM 利用時は make run FLUTTER="fvm flutter" DART="fvm dart" のように上書き。make help で全ターゲット一覧。
Windows:
flutter pub get
dart run build_runner build
flutter run -d windows --dart-define-from-file=dart_defines/prod.json
make を使わない macOS 向け同等コマンド:
flutter pub get
dart run build_runner build
flutter run -d macos --dart-define-from-file=dart_defines/prod.json
使い方
📖 スクリーンショット付きの詳しい使い方ガイドは yahiro.tech/roola/usage にまとまっています。以下は要点の抜粋です。
初回起動
アプリを起動するとワークスペース(Explorer タブ)が開きます。左側にお気に入り・ランチャーのサイドバー、中央にタブ式の 3 ペイン、トップバーにアクティビティモニタ・ノートパッド・設定があります。
ランチャーにエントリを登録する
サイドバーの「ランチャー」セクション右端の「+」または「管理…」リンクから登録画面を開きます。動作タイプは 3 種類:
| 動作タイプ | 用途 |
|---|---|
| シェルを開く | $SHELL を対象ディレクトリで起動(コマンドなし) |
| コマンドを実行 | 任意コマンドを $SHELL -ilc 経由で実行。.zshrc の PATH を継承するので pnpm / nvm / Homebrew 配下のツールもそのまま動く。完了後にシェルを継続させるオプションあり |
| Claude Code Skill | claude /<skill-name> を起動。Skill 名を指定。Claude Code CLI がインストールされていないと選択肢自体が出ません |
登録済みエントリは 1 階層のフォルダでグルーピング可能。ランチャー管理画面でドラッグ & ドロップで整理できます。
エントリを起動する
サイドバーのエントリをクリックすると PTY セッションが立ち上がり、ワークスペースのターミナルタブに表示されます。状態遷移:
起動中… → 実行中 → 入力待ち → 完了 (0) / 失敗 / キャンセル
セッションは「閉じる」を押すまで残り、終了済みの出力履歴も保持されます。

ターミナル操作
通常のターミナルと同じ感覚で:
- テキスト入力 + Enter:
\n付きで PTY に書き込み - Shift+Enter: LF 改行をそのまま入力(ADR-0032。Claude Code 等の複数行入力用)
- 承認応答:
y/n等でclaudeなどの確認プロンプトに応答 - 矢印キー / Ctrl-C / ウィンドウリサイズ: ANSI 制御に対応、PTY 側 cols/rows も自動追従
3 ペインタブ式ワークスペース
タブを 3 ペイン(左上 / 右上 / 下)に自由に配置し、レイアウトを保存します(ADR-0026 / 0028)。タブをドラッグして移動・並べ替え、ペインの分割は境界をドラッグでリサイズ。
エクスプローラタブ
- ナビゲーション: ダブルクリックでサブディレクトリに遷移(ADR-0021)。ペインヘッダの戻る / 進むで履歴を移動
- シングルクリック: 選択(パスバーに反映)
- キーボード操作: 一覧を一度クリックしてフォーカスを得たあと、
↑/↓で選択を移動、Enterで開く(ディレクトリは遷移、ファイルは OS デフォルトアプリ)、→でディレクトリに侵入、←で親へ戻る(ADR-0051) - Cmd+C: 選択中アイテムの絶対パスをコピー
- タイル表示密度: 設定画面で「コンパクト / ゆったり」を切替(ADR-0024)
- 右クリックメニュー: Finder で表示・名前変更・コピー・ペースト・新規ファイル / フォルダ・プロパティ等
ファイルプレビューパネル
エクスプローラタブでファイルを選択すると、右ペインに読み取り専用のプレビューが開きます(ADR-0046 / 0050)。
- 対応形式: コード / テキスト(シンタックスハイライト付き)、画像(PNG / JPEG / GIF / WebP / BMP)、PDF
- 自動開閉: 既定は非表示。プレビュー可能なファイルを選ぶと自動で開き、ディレクトリやバイナリ・大きすぎるファイルを選ぶと自動で閉じる
- 操作: 画像 / PDF はパン・ズーム可。テキストは選択・コピーのみ(編集はできません。編集したいときは右クリック → 外部アプリで開く)
- 更新: パネル右上のトグルで開閉、リフレッシュボタンで再読込。表示状態・幅はタブごとに保持(永続化はしない)

Git ビュータブ
Git 管理下のディレクトリで「Git ビューを開く」を選ぶと、新しいタブとして開きます(ADR-0030):
- Changes: working tree の変更ファイル一覧と diff
- History: コミットグラフと選択コミットの詳細
- Branches: ブランチ作成・切替・stash の退避と適用
- Actions: フェッチ / プル / プッシュ

ノートパッド
トップバーのメモアイコンから開閉できる、ワークスペース外のフローティングパネル(ADR-0036)。雑なメモ用途に割り切った最小構成で、本文はアプリ起動間も自動保存されます。
アクティビティモニタ
トップバーに常駐する CPU / メモリの占有ミニゲージ(ADR-0039)。クリックで上位プロセス一覧のポップオーバーが開きます。
キーボードショートカット
設定画面の「キーボードショートカット」リンク、または ⌘, の隣のリンクから一覧と編集画面を開けます(ADR-0033)。各行をクリックするとキーコンビ記録ダイアログが開き、修飾キーを含む新しいキーに割り当てできます。⌘C / ⌘V / ⌘X / ⌘A / ⌘Z はテキスト編集用に予約済み(ADR-0035)。
外観のカスタマイズ
設定画面の「外観」セクションで以下を切替えます(ADR-0038):
- 不透明: Polaris の基底色(グラファイト)
- 透過: 半透明にしてデスクトップを透かす。透過率はスライダーで調整可
- アクセント色: ゴールド(既定)/ アイスブルー
表示言語の切替
設定画面の「言語」で日本語 / 英語を切替(ADR-0034)。即時反映されます。
Compatible with Claude Code
Claude Code CLI(Anthropic の公式コマンドラインツール)がインストールされていると、以下が自動で有効化されます(ADR-0022):
- 設定画面に
claude --versionのヘルスチェックバナーを表示 - エクスプローラの
.claude/skills/を検知し、特別アイコンと Skill チップを表示 - フォルダ右クリックメニューに 「このディレクトリで Claude Code を開く」「
<skill>を即実行」「<skill>をランチャーに登録」を追加 - ランチャー登録時の動作タイプに 「Claude Code Skill」 を選択可能
Claude Code は オプショナルな統合 であり、未インストールでも Roola 本体は完全に動作します。Roola は Claude / Anthropic の公式プロダクトではなく、互換アプリです。
GUI 起動経路(Dock / Finder)では launchd 由来の最小 PATH に切り詰められるため、Roola はヘルスチェックでも PTY 起動でも
$SHELL -ilc経由で claude を呼びます(.zshrcの PATH 拡張を継承)。
タスク通知(OSC・設定ゼロ)
ペイン内で実行中の CLI ツールが出す 通知エスケープシーケンス(OSC 9 / OSC 777) を、Roola が OS 通知に中継します(ADR-0066)。iTerm2 / Ghostty / kitty などのモダンターミナルと同じ仕組みで、フック登録や設定は一切不要 — インストール直後から動きます(初回の通知時に OS の通知許可を求めるダイアログだけ出ます)。

Claude Code の場合、通知が出るタイミングは次の 2 つです:
| イベント | タイミング |
|---|---|
| 許可待ち("Claude needs your permission") | 発生した瞬間 |
| 入力待ち("Claude is waiting for your input") | ターン完了から約 60 秒放置で発火(claude の標準設定 messageIdleNotifThresholdMs で短縮可能) |
- 通知クリックで該当ペインへフォーカスが戻ります(タブを閉じた後の通知クリックは何もしません)
- 見ているペインからは通知しません — フォーカス中のペイン(とフォーカス状態を受け取った claude 自身)は通知を抑制します
- claude 以外のツールも
printf '\e]9;本文\a'(OSC 9)やprintf '\e]777;notify;タイトル;本文\a'(OSC 777)で同じ通知が出せます - 同一ペインからの連続通知はレート制限されます(通知シーケンスを含むファイルの
catなどによる通知洪水の対策)
旧方式(Stop フック + ローカル HTTP 受信口・ADR-0057)は 撤去済み です。旧バージョンでフックを登録(自動インストール)していた場合、残ったフックは無害(静かに失敗するだけ)ですが、
~/.claude/settings.jsonのhooks.Stopから該当エントリを手動で削除することをお勧めします。
トラブルシューティング
| 症状 | 対処 |
|---|---|
ランチャーで command not found | which <command> でターミナルから動くか確認。動くのに Roola から動かない場合は .zshrc の PATH 設定を見直し(Roola は $SHELL -ilc 経由で実行するので .zshrc の設定が継承されます) |
| 「Claude Code が見つかりません」と表示される | which claude で確認。複数バージョンが PATH 上に共存していると古い方が選ばれることがあります |
| 「ディレクトリが見つかりません」とエラー | エントリ編集でディレクトリパスを正しい値に更新 |
| ターミナル描画が崩れる | ウィンドウサイズを変更すると再レイアウトされます |
Mac スリープから復帰したら一部 Skill が failed になっている | スリープ中に API への SSE ストリーミングがタイムアウトで切断されたため。承認待ち / 完了済みのセッションは影響なし。chip を「閉じる」で破棄して必要なら再実行してください |
| タスク通知が出ない | ①該当ペインがフォーカス中でないか(見ている画面からは通知しない仕様。別ペインかアプリへ切り替えて確認) ②OS の通知設定で Roola が許可されているか ③claude の完了通知はターン完了の瞬間ではなく約 60 秒放置後に出る仕様(上記「タスク通知」参照) ④printf '\e]9;test\a' をペインで実行して切り分け(これで出れば受信側は正常) |
| 永続化されたエントリ・設定をリセットしたい | make reset(prod / dev の Application Support 配下を両方削除) |
既知の制約
- Linux は非対応
- App Sandbox は 無効化 されています(macOS。PTY 起動と任意ディレクトリへのアクセスのため)
- Windows 固有: ターミナルは xterm.js(WebView2)ベース
riverpod_lint/custom_lintは riverpod 3.x との依存解決の都合で当面保留中(ADR-0007)- 実 PTY 上での完了・キャンセル系のテストは
flutter testのテストバインディングでは検証できずintegration_test対象
開発者向け情報
設計判断の時系列記録は docs/adr/ を参照(最新一覧は docs/adr/README.md)。アーキテクチャの詳細は docs/architecture.md、コーディング規約は docs/coding-standards.md。
仕様駆動開発として OpenSpec を併用しています。
開発時の典型コマンド:
make watch # コード生成を watch モードで起動
make check # format → analyze → test(CI 相当)
make dmg # ビルド + 署名 + 圧縮 DMG 作成
make dist # 上記 + Apple へ提出して公証 + ステープル
make reset # 永続化されたエントリ・設定を削除
リリース手順(タグ push で自動配布)は docs/release.md を参照。
Project status / Support
Roola は個人の週末プロジェクトとして開発されている OSS です。「自分が使うため」が 第一の目的で、コミュニティサポート義務は負いません。
- Issue / PR の方針:
- issue は再現可能な最小ケース(テンプレート に沿った報告)から優先的に扱います。要望系の issue にも反応しない可能性があります。
- PR は歓迎しますが、メンテナの方針に合わないものは merge されないこともあります。 大きい変更を送る前に、まず issue で方針を確認することをお勧めします。
- CLA(Contributor License Agreement)は取りません。
- ロードマップは公開しません。次に何を作るかはメンテナの気分次第です。
- 後方互換性は最小限: メジャーバージョン 0.x の間は破壊的変更が予告なく入ります。
連絡が必要な場合は GitHub Issue 経由でメンションしてください。
ライセンス
Copyright (c) 2026 Yahiro