convez.ai
SkillDevOps & InfraestruturaIntermediário
yahir0

Roola

yahir0/Roola

Explorador de arquivos com terminal, Git e integração Claude Code

Ver no GitHub
BomPluginScore · de 0 a 100

Explorador 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/Roola

1 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

Estrelas
8
Forks
0
Acompanhando
1
Saúde
57%
Último commit
há 1 mês
Versão
v0.0.49
Issues abertas
5
Contribuidores
3

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)。

Roola workspace


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+Enter inputs 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, Enter to 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 --version healthcheck 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:

  1. DMG をダウンロード: Releases ページから最新版を取得(公証 + ステープリング済み)。
  2. インストール: DMG を開いて Roola.app を Applications フォルダにドラッグ。
  3. 起動: Launchpad もしくは Spotlight から Roola で起動。

Windows:

  1. インストーラをダウンロード: Releases ページから RoolaSetup-x.x.x.exe を取得。
  2. インストール: インストーラを実行してウィザードに従う。
  3. 起動: スタートメニューまたはデスクトップショートカットから起動。

自分でビルドしたい場合は 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 秒で通知。通知クリックで該当ペインへフォーカス復帰。

動作環境

プラットフォーム要件
macOSmacOS 14(Sonoma)以降(Apple Silicon / Intel)
WindowsWindows 10 / 11(64-bit)

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 Skillclaude /<skill-name> を起動。Skill 名を指定。Claude Code CLI がインストールされていないと選択肢自体が出ません

登録済みエントリは 1 階層のフォルダでグルーピング可能。ランチャー管理画面でドラッグ & ドロップで整理できます。

エントリを起動する

サイドバーのエントリをクリックすると PTY セッションが立ち上がり、ワークスペースのターミナルタブに表示されます。状態遷移:

起動中… → 実行中 → 入力待ち → 完了 (0) / 失敗 / キャンセル

セッションは「閉じる」を押すまで残り、終了済みの出力履歴も保持されます。

Launcher in action

ターミナル操作

通常のターミナルと同じ感覚で:

  • テキスト入力 + 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 はパン・ズーム可。テキストは選択・コピーのみ(編集はできません。編集したいときは右クリック → 外部アプリで開く)
  • 更新: パネル右上のトグルで開閉、リフレッシュボタンで再読込。表示状態・幅はタブごとに保持(永続化はしない)

File preview

Git ビュータブ

Git 管理下のディレクトリで「Git ビューを開く」を選ぶと、新しいタブとして開きます(ADR-0030):

  • Changes: working tree の変更ファイル一覧と diff
  • History: コミットグラフと選択コミットの詳細
  • Branches: ブランチ作成・切替・stash の退避と適用
  • Actions: フェッチ / プル / プッシュ

Git view

ノートパッド

トップバーのメモアイコンから開閉できる、ワークスペース外のフローティングパネル(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 の通知許可を求めるダイアログだけ出ます)。

Task completion notification

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 foundwhich <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 経由でメンションしてください。

ライセンス

MIT License

Copyright (c) 2026 Yahiro

Ver o original no GitHub

Bom para

Relacionados