Corral

corralctl

Finder で扱いやすいコレクション、エコシステム、メタデータを使って、GitHub、GitLab、Gitea、Forgejo、Codeberg、Bitbucket のリポジトリを自動的にクローンし、整理します。

目次

はじめに

• インストール — mise、Homebrew、Arch、Nix、Go、またはソースから
• クイックスタート — 1 つのコマンドでクローンして整理

機能と機能性

• 機能 — 構造化されたレイアウト、並行処理、セキュリティ
• アーキテクチャ — API の取得からリポジトリごとのディスパッチまでのエンドツーエンドのフロー
• 対話型 TUI モード — キーバインド、コマンド、自動補完
• レイアウトのカスタマイズ — Apple 風のコレクション、エコシステム、カスタムテンプレート
• スマート同期 — ネットワークを最適化した差分更新
• Exec モード — Git コマンドの並行バッチ実行
• 他のフォージへのミラーリング — corralctl sync でツリーを GitLab、Gitea、Forgejo、Codeberg、Bitbucket、または GitHub にプッシュ
• MCP サーバー — ローカルのワークスペースを AI コーディングエージェントに公開
• リポジトリ横断シンボル検索 — すべてのクローンを対象に、任意の定義場所を検索

リファレンスと運用

• 使用方法とフラグ — CLI パラメーターの完全なリファレンス
• 例 — 実行可能なプログラム例のインデックス
• トラブルシューティング — よくあるエラーの簡単な解決方法
• よくある質問 — 設計上の判断と Windows／WSL のサポート

プロジェクト

• ドキュメント — マニュアル、API リファレンス、開発者向けドキュメント
• corralctl を使わない場合 — 正直な制限事項
• 要件とツールチェーンのポリシー — Go の最低バージョンと引き上げのタイミング
• 安定性の保証 — このプロジェクトにおける破壊的変更の意味
• セキュリティと強化 — 報告、セキュリティ体制、ファジング
• ライセンス

インストール

mise（macOS／Linux）

mise use -g github:sebastienrousseau/corralctl

最新リリースの corralctl バイナリをインストールし、他の mise ツールと一緒に管理できます。

Homebrew（macOS）

brew install sebastienrousseau/tap/corralctl

ここでの Homebrew は macOS 専用の仕組みである Cask です。Linux で brew install を実行すると拒否されます。Linux では .deb／.rpm パッケージまたは各リリースに添付されている tarball を使用するか、mise またはGo ツールチェーンでインストールしてください。

Arch Linux（AUR）

yay -S corralctl-bin    # or: paru -S corralctl-bin

Nix（すべてのプラットフォーム）

nix run github:sebastienrousseau/corralctl -- --help   # run without installing
nix profile install github:sebastienrousseau/corralctl # install

flake にはバイナリ、man ページ、シェル補完が含まれています。また、nix develop を実行すると、プロジェクトの CI ゲートに必要なすべてのツールが揃ったシェルが起動します。ツールのバージョンは flake.lock で固定されています。

Go ツールチェーン

go install github.com/sebastienrousseau/corralctl/cmd/corralctl@latest

$(go env GOPATH)/bin（または $GOBIN が設定されている場合はその場所）にインストールされます。この方法でビルドしたバイナリは corralctl version dev と表示されます。実際のバージョンはリリースパイプラインで -ldflags を使って埋め込まれますが、go install では適用されません。--version に意味のある値を表示する必要がある場合は、リリース成果物を使用してください。

ソースからビルド

Git と、go.mod の go ディレクティブで指定されたバージョン以上の Go が必要です。ただし、到達可能な crypto/x509 のアドバイザリがある Go 1.27.0 から 1.27.2 は対象外です（最低ツールチェーンポリシーを参照）：

git clone https://github.com/sebastienrousseau/corralctl.git
cd corral
make install            # installs ~/.local/bin/corralctl

プラットフォームの前提条件

brew install go git gh

sudo apt install golang git

sudo dnf install golang git gh

クイックスタート

所有者名（GitHub のユーザー名または組織名）を指定して corralctl clone を実行すると、すべてのリポジトリをクローンし、整理されたローカルディレクトリ階層に自動で振り分けます。

# Log in to GitHub CLI first (or set GITHUB_TOKEN)
gh auth login

# Clone and organise every repository for your profile
corralctl clone my-username

省略形の corralctl my-username でも同じ操作を実行できます。バイナリは 1 つ、ベースコマンドも 1 つで、すべての操作はそのサブコマンドです。

ローカルのディレクトリ構造を、次のような体系化されたミラーにまとめます。

~/Code/
├── Public/
│   ├── Go/
│   │   └── corral/
│   ├── Rust/
│   │   └── my-crate/
│   └── Web/
│       └── project.github.io/
├── Private/
│   └── Python/
│       └── internal-tool/
├── Forks/
│   └── Rust/
│       └── upstream-project/
└── Work/

macOS では、corralctl はリポジトリフォルダにネイティブの Finder タグも書き込みます。自分で追加したタグは保持されます。これにより、実際の階層を浅く保ちながら、Finder の検索やスマートフォルダを複数のエコシステムにわたって活用できます。

機能

アーキテクチャ

1 回の実行で git を解決し、フォージ（GitHub、GitLab、Gitea、Forgejo、Codeberg、Bitbucket）からすべてのリポジトリを並行して取得します。必要に応じて対話形式で対象を選択でき、その後、ワーカープールにクローン／スマート同期／スキップの判断を振り分けます。スマート同期では、リポジトリごとの .corral-state.json サイドカーファイルを参照し、アップストリームの pushed_at が変わっていない場合は git pull を省略します。

graph TD
    A[User Shell] --> B{corralctl}
    B --> C[Pre-flight: exec.LookPath git]
    C -- Missing --> Z1[Exit: git not found on PATH]
    C -- OK --> D[Resolve auto/token/gh auth]
    D --> E[Forge API: list repos]
    E --> E1["First page<br/>+ resp.LastPage"]
    E1 --> E2{LastPage > 1?}
    E2 -- Yes --> E3["Concurrent fetch<br/>pages 2..N (max 5)"]
    E2 -- No --> F
    E3 --> F[Filtered repository set]
    F --> F1{TUI selector?}
    F1 -- "--select" --> F2[Interactive TUI<br/>/sort, /all, /none, search]
    F1 -- No --> G
    F2 --> G[Layout template render<br/>Collection/Bucket/Name]
    G --> H["Worker pool<br/>(--concurrency)"]
    H --> I{Already cloned?}
    I -- No --> J["git clone (+ blobless/<br/>depth/single-branch)"]
    I -- "Yes (--no-sync)" --> K[SKIP]
    I -- Yes --> L{Smart sync:<br/>pushed_at advanced?}
    L -- No --> M[SKIP up-to-date]
    L -- "Yes (or --force-sync)" --> LG{"Operation in progress,<br/>local commits ahead,<br/>or no upstream?"}
    LG -- Yes --> LR[ERROR: pull refused]
    LG -- No --> N[git pull --rebase --autostash]
    N --> N1["+ optional submodule update<br/>(--ignore-submodule-failures)"]
    J & N1 --> O[Stamp .corral-state.json]
    O & K & M & LR --> P{All workers done?}
    P -- No --> H
    P -- Yes --> Q[Cleanup empty legacy dirs]
    Q --> R{--orphans?}
    R -- Yes --> S[Walk baseDir<br/>parse .git/config]
    R -- No --> T[Print summary]
    S --> T

インタラクティブ TUI モード

-i または --interactive フラグを渡すと、選択ダッシュボードを起動できます。

./corralctl -i my-username

キーバインド

• [space] — 現在のリポジトリの選択状態を切り替えます。
• [ctrl+a] — 現在のフィルターに一致するリポジトリをすべて選択します。
• [ctrl+n] — 現在のフィルターに一致するリポジトリの選択をすべて解除します。
• [/] — コマンド／フィルターモードに入ります。
• [enter] — 選択を確定し、クローン／同期を開始します。
• [esc] — アプリケーションを何も表示せずに終了します。

セッション内コマンド

TUI 内で / を押すと、コマンドモードに入ります。コマンドはプレフィックスベースの自動補完に対応しています（自動補完するには [tab] または [right-arrow] を押します）。

• /sort <field> — リポジトリを並べ替えます。フィールド：
  • name — リポジトリ名のアルファベット順で並べ替えます。
  • language / lang — 言語のアルファベット順で並べ替えます。
  • visibility / vis — 公開設定（Private/Public）のアルファベット順で並べ替えます。
  • public — 公開リポジトリを先頭に優先して表示します。
  • private — 非公開リポジトリを先頭に優先して表示します。
• /all — フィルタリングされたリポジトリをすべて選択します。
• /none — フィルタリングされたリポジトリの選択をすべて解除します。
• /exit / /quit — キャンセルして、何も表示せずに終了します。
• /help — セッション内のヘルプパネルをオーバーレイ表示します。

レイアウトのカスタマイズ

デフォルトでは、corralctl は Apple スタイルのレイアウト {{.Collection}}/{{.Bucket}}/{{.Name}} を使用します。フォークには Forks コレクションが使用され、.github.io リポジトリには、検出された言語にかかわらず Web バケットが使用されます。--layout フラグを使うと、これを上書きできます。

./corralctl --layout "{{.Owner}}/{{.Name}}" my-org

使用できるプレースホルダー：

• {{.Owner}} — GitHub のオーナー名。
• {{.Name}} — リポジトリ名。
• {{.Collection}} — 標準ルート（Public、Private、または Forks）。
• {{.Bucket}} — Finder に表示されるエコシステムのバケット（Go、Rust、Web など）。
• {{.Language}} — 小文字に正規化された主要言語。
• {{.Visibility}} — 小文字に正規化されたリポジトリの公開設定。

macOS Finder のカラーラベルとタグ

macOS では Finder のタグ付けがデフォルトで有効になっており、 --finder-tags=false で無効にできます。corralctl は macOS ネイティブの拡張属性（com.apple.metadata:_kMDItemUserTags および com.apple.FinderInfo）を使用して、各リポジトリフォルダーを自動的に分類し、 視覚的な色付きの点とフォルダーのカラーラベルを適用します。

運用状況を示す高精度の分類体系

Finder のフォルダカラーの同期

corralctl は Spotlight メタデータ（_kMDItemUserTags）と macOS ネイティブの Finder ディレクトリラベル（com.apple.FinderInfo の 9 バイト目、ビット 1～3）の両方を同期します。これにより、 Finder ウインドウのリスト表示、アイコンのバッジ、Finder サイドバーのカラー フィルターに、各リポジトリの運用状態がリアルタイムで正確に反映されます。

ワークスペースのすべてのフォルダタグは、いつでも監査して再同期できます。

corralctl doctor ~/Code --refresh-tags

検索可能なメタデータタグ

カラーのドットに加えて、corralctl は macOS の Finder と Spotlight によって自動的にインデックスされるプレーンテキストのタグを書き込みます。

• Ecosystem: <Language>：言語カテゴリで検索できます（例：Ecosystem: Go、Ecosystem: Rust、Ecosystem: Python、Ecosystem: Web）。
• Visibility: <Visibility>：Visibility: Public または Visibility: Private。
• Collection: <Collection>：Collection: Public、Collection: Private、Collection: Forks、または Collection: Work。
• Owner: <Owner>：リポジトリのオーナーまたは組織の名前空間（例：Owner: sebastienrousseau）。
• Forge 識別子：GitHub、GitLab、Gitea、Forgejo、Codeberg、または Bitbucket。
• リポジトリの特性：Fork、Template、Mirror、Archived。

Finder の検索とスマートフォルダ

macOS の Finder でこれらのタグを組み合わせて、コードを整理し、移動できます。

• Finder サイドバー：Finder のサイドバーで任意の色をクリックします（例：Green をクリックすると進行中のプロジェクトが表示され、Blue をクリックするとクリーンな参照用クローンが表示されます）。
• Spotlight と Finder の検索：Finder で Cmd+F を押して検索します。
  • tag:"In-Flight" - 未コミットまたは未プッシュの作業があるアクティブなプロジェクトを表示します
  • tag:Pristine - クリーンであることが確認済みのクローンを表示します
  • tag:"Needs Fix" - 壊れている、または競合しているリポジトリを探します
  • tag:Go または tag:"Ecosystem: Go" - 言語でコレクションを横断して絞り込みます
• スマートフォルダ：検索を保存して、Finder サイドバーに常時表示されるスマートフォルダとして利用できます。

個人タグの保持

corralctl は、ユーザーが定義したタグ（Client、Urgent、Review など）を削除したり上書きしたりすることはありません。既存のファイルタグを読み取り、管理対象の分類体系だけを更新し、カスタムタグをデータ損失なく適切に統合します。

スマート同期

corralctl は、各リポジトリの .git/ フォルダの隣にある .corral-state.json サイドカーファイルに同期メタデータを保存します。

• 冗長なプルを回避： 前回の同期以降にリモートリポジトリへの新しいプッシュがない場合、git pull は完全にスキップされます。
• 上書き： スマートチェックを回避して corralctl に完全な git pull を実行させるには、--force-sync フラグを渡します。
• 同期を完全にスキップ： すべてのクローン済みリポジトリの更新をスキップするには、--no-sync を渡します。

Exec モード

整理したリポジトリ全体で、任意のシェルコマンドを並行して実行します。

# Check git status for all Go/Rust private repositories
./corralctl exec "git status -s" --languages go,rust --visibility private

• シェル： コマンドは、Unix では /bin/sh -c、Windows では cmd.exe /C を通じて実行され、$SHELL の指定内容には依存しません。別のシェルを使うには、コマンド内でそのシェルを指定してください。
• 期限： --timeout 2m を指定すると、各リポジトリに個別の期限が設定されます（デフォルトは 0 で、期限なし）。期限を超過したコマンドは子プロセスとともに強制終了され、失敗としてカウントされます。
• コレクション： --visibility には all またはトップレベルのコレクション（public、private、work、forks）を指定します。
• マシン出力： --output json または --output ndjson を指定すると、リポジトリごとに 1 件のレコード（repo、exit_code、duration_ms、stdout、stderr、timed_out）が出力されます。

他のフォージへのミラーリング

corralctl sync はワークフローの外向きの処理です。あるフォージから clone で取り込んだ内容を、sync で他のフォージにプッシュすることで、整理されたツリーが、利用したいすべてのホスト上のミラーの信頼できる情報源になります。

export GITLAB_TOKEN=glpat-…            # scope: api
export GITEA_TOKEN=…                   # scope: write:repository

corralctl sync --to gitlab --to gitea@https://git.example.com --dry-run
corralctl sync --to gitlab --to gitea@https://git.example.com

ベースディレクトリ配下のすべてのリポジトリについて、各同期先にリポジトリが存在しない場合は作成し、フォージ名を付けたリモートを設定して、1 回の往復でプッシュします。

git push --prune --no-verify <forge> refs/heads/*:refs/heads/* +refs/tags/*:refs/tags/*

同期先には、すべてのローカルブランチとタグが作成され、それ以外は作成されません。ブランチが強制プッシュされることはありません。同期先でブランチが進んでいる場合は、上書きせず、拒否して報告します。タグはローカルの名前空間に従います。

「ローカル」とは、クローン自身のブランチ（refs/heads/*）を指します。つまり、同期先にミラーされるのはクローンであり、そのクローンのオリジンではありません。corralctl clone または git clone で作成したクローンには、デフォルトブランチだけがローカルにあります。それ以外のアップストリームブランチはリモート追跡参照（origin/<name>）としてのみ存在し、プッシュされません。プッシュ時には不要なブランチが削除されるため、そのようなブランチが同期先にすでに存在する場合も削除されます。同期先で直接作成されたブランチも同様です。ブランチを引き継ぐには、sync の実行前にローカルでチェックアウトしてください（git switch <name>）。

新しい同期先がパブリックとして作成されるのは、次の 2 つの条件をどちらも満たす場合に限られます。前回 corralctl clone で一覧表示した際に、ソースフォージがリポジトリをパブリックと報告していること（その情報はクローンの状態サイドカーに記録されています）、そしてクローンが Public/ ディレクトリ配下にあることです。それ以外はすべてプライベートとして作成されます。corral で作成されていないクローンや、0.0.54 より前に作成されたクローンも対象です。ディレクトリ名だけでは推測にすぎず、アップストリームでプライベートに変更されたリポジトリが Public/ 配下に残っている可能性もあります。記録を最新にするため、sync の前に所有者の corralctl clone を実行してください。--dry-run を指定すると、各同期先に設定される公開範囲を確認できます。

同期先は <forge>[:<owner>][@<url>] 形式で指定します。

認証情報には、フォージから一覧を取得するために clone が使用する環境変数と同じものを使います。Gitea 系では、GITHUB_TOKEN（または gh CLI）、GITLAB_TOKEN、BITBUCKET_TOKEN、GITEA_TOKEN、FORGEJO_TOKEN、CODEBERG_TOKEN を使用できます。いずれも CORRAL_ を付けた名前でも使用できます。デフォルトの HTTPS では、同じトークンでプッシュを認証します。認証のスコープはそのフォージのオリジンに限定され、.git/config に書き込まれることはありません。--protocol ssh を指定すると、代わりに鍵を使用します。

3 つの拒否条件が組み込まれています。1 つ目は、同じ名前のローカルリポジトリが 2 つある場合です。元のリポジトリの隣にフォークを置いていると、同期先の同じパスに配置されるため、両方について報告され、他のツリーの処理は続行されますが、どちらもプッシュされません。2 つ目は、リポジトリを、その origin があるフォージにプッシュすることは決してないという点です。corral は 6 つのフォージからクローンするため、ツリー内に、オリジンが同期先でもあるクローンが含まれる場合があります。自分自身のアップストリームを対象に不要なブランチを削除するのは、ミラーリングではありません。3 つ目は、同期先に同名のリポジトリがすでに存在し、公開範囲が異なる場合です。この場合はエラーになり、黙って再利用されることはありません。

結果は --output text、json、ndjson で標準出力に出力されます。いずれかのリポジトリで失敗すると終了コードが 0 以外になるため、cron ジョブで通知できます。これはスタンドアロンの corral-sync ツールに代わるもので、既存のクローンをそのまま引き継げるよう、gitlab と gitea のリモート名は維持されています。

MCP サーバー（AI エージェント向け）

corralctl には、ローカルにある corralctl で整理されたワークスペースを AI コーディングエージェント（Claude Code、Cursor、Cline、Codex CLI、Aider、その他 MCP に対応するもの）に公開する Model Context Protocol サーバーが含まれています。デフォルトの読み取り専用モードではネットワーク呼び出しは行われず、GitHub API に接続することもありません。このサーバーは、すでにディスク上にあるクローンを参照する窓口です（--enable-mutations を指定すると corral_clone_repo と corral_sync_repo が追加され、git をシェルから実行するためネットワークに接続します。それでも GitHub API に接続することはありません）。

GitHub 公式の MCP サーバーがリモート API（イシュー、PR、検索）を扱うのに対し、corral-mcp はそれだけが扱える領域、つまり可視性と言語別に整理されたローカルミラーを、往復通信なしでクエリできるようにします。

ツール

• corral_list_repos — 可視性／言語／名前／同期状態でローカルクローンを絞り込みます
• corral_find_repo — あいまいな名前からクローンを特定します（一意に特定できない場合は候補を返します）
• corral_get_repo_metadata — 現在のブランチを含む、1 つのクローンの完全なメタデータを取得します
• corral_status_summary — ワークスペースの概要：可視性と言語別の件数
• corral_workspace_index — 1 回の呼び出しで完全な構造化インデックスを取得します
• corral_find_symbol — すべてのクローンから、シンボルが宣言されている場所を探します
• corral_search_code — すべてのクローンから、テキストが出現する場所を探します
• corral_repo_overview — 1 回の呼び出しで 1 つのリポジトリの構成を取得します
• corral_discover_repos — ローカルディスク上の未追跡または未管理のリポジトリを検出します

書き込みツール（v0.0.12、--enable-mutations でオプトイン）：

• corral_sync_repo — 1 つのクローンに対して git pull --rebase --autostash を実行します。プル前には corralctl clone と同じチェックを行います。origin がないクローン、またはインデックスの読み込み後に origin が変更されたクローン、コミットがないクローン、デフォルトブランチ origin/HEAD が指すブランチにいないクローンでは実行を拒否するため、エージェントがフィーチャーブランチをリベースすることはありません。corral_delete_repo と同じクローン単位のロックを保持します。sync と同様、リベース、マージ、チェリーピック、リバート、ビセクトが進行中の場合、ブランチにアップストリームにないコミットがある場合、またはアップストリームが設定されていない場合も実行を拒否します。
• corral_clone_repo — サンドボックス化されたターゲットパスに URL のクローンを作成します
• corral_adopt_repo — 任意で移動やリモートの作成を行い、ローカルリポジトリを取り込みます。セルフホストの forge_url は、オペレーターが corralctl mcp --forge-url に渡したものに限られます
• corral_delete_repo — クローンを削除します。--enable-destructive-mutations が必要です。未コミットまたは未プッシュの変更がある場合は実行を拒否し、削除のたびに人による承認を求めます

すべての変更操作は、次の場所に JSONL 監査記録を書き込みます。 $XDG_STATE_HOME/corral/mutations.log（または ~/.local/state/corral/mutations.log）。 記録にはツール、対象、引数、結果、タイムスタンプが含まれます。各変更操作につき、操作前に永続化される意図と、操作 ID で紐付けられた完了の 2 件が記録されます。意図を記録できない場合、変更操作は実行されません。

保存先を変更するには --audit-log <path> を指定します。ファイルは 8 MiB でローテーションされ、直近 3 世代（mutations.log.1 … .3）が保持されるため、長時間稼働するサーバーがディスクを使い切ることはありません。

プロンプト（v0.0.12）

• explain_workspace — 読み取り専用ツールを使ってワークスペースを調査し、その概要をまとめるようエージェントに依頼します
• identify_stale_repos — .corral-state.json で最近同期されていないことが示されているクローン（デフォルト：30 日）を見つけるようエージェントに依頼します

リソース

• corral://workspace/index
• corral://repo/{owner}/{name}/state
• corral://repo/{owner}/{name}/tree
• corral://repo/{owner}/{name}/file/{path}（上限 1 MiB、パストラバーサル対策済み）

インストール

Claude Code:

claude mcp add corral -- corralctl mcp

Cursor / Cline（mcp.json）：

{
  "mcpServers": {
    "corral": {
      "command": "corralctl",
      "args": ["mcp"]
    }
  }
}

Docker（ローカルへのインストール不要） — MCP Registry が告知しているものと同じバイナリを、ワークスペースにマウントして実行します。

{
  "mcpServers": {
    "corral": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--user", "1000:1000",
        "-v", "${HOME}/Code:/workspace:ro",
        "ghcr.io/sebastienrousseau/corralctl:latest",
        "mcp", "--root", "/workspace"
      ]
    }
  }
}

引数に関する注意事項：

• --user 1000:1000 — ホストの UID:GID（id -u:id -g）に置き換えると、コンテナ化されたスキャナーがマウントされたワークスペースをホストユーザーと同じ権限で読み取れます。これを指定しない場合、イメージはコンテナ内でシステム UID として実行されるため、ワークスペースでグループまたはユーザーのみにアクセスを制限しているディレクトリで permission denied が発生します。
• -v … :ro — 読み取り専用のマウントです。v0 のツールはもともと読み取り専用ですが、:ro を指定することで、そのことを明示し、権限のない書き込みをサーバーに要求する悪意あるエージェントから保護できます。
• --root /workspace — コンテナ内のサンドボックスルートです。すべてのツールとリソースのパスチェックはこのプレフィックスの範囲に限定され、エージェントの要求内容にかかわらず、その範囲外のリクエストは拒否されます。

別のルートをサンドボックス化する（デフォルトは --base-dir、次に $HOME/Code）：

corralctl mcp --root /custom/workspace

トランスポート

デフォルトは stdio です。クライアントが corralctl mcp を起動し、パイプを管理します。 ほかの2つは --host と --port で待ち受けるため、別のユーザーが起動した サーバーに接続するクライアント向けです。

--http 127.0.0.1:7777 は --transport streamable-http の旧表記ですが、引き続き使用できます。

待ち受ける各トランスポートは、デフォルトでループバックにバインドされます。--host 0.0.0.0 または すべてのインターフェースにバインドする --http :7777 は、このサーバーが ルート配下のすべてのリポジトリを公開するため、拒否されます。--allow-remote でこの拒否を解除するには、 ファイルまたは環境変数から読み込むベアラートークンも必要です。

export CORRAL_MCP_TOKEN="$(cat ~/.config/corral/mcp-token)"
corralctl mcp --transport streamable-http --host 0.0.0.0 --allow-remote
# or: corralctl mcp ... --allow-remote --token-file ~/.config/corral/mcp-token

Authorization: Bearer <token> のないリクエストや、トークンが間違っているリクエストには、 WWW-Authenticate チャレンジを付けて 401 を返します。--token も引き続き使用できますが、 非推奨です。コマンドライン上の内容は、マシン上のすべてのユーザーが ps で確認できるためです。サーバーは平文の HTTP で通信し、TLS リスナーを備えていません。そのため、TLS 終端リバースプロキシを前段に置かない限り、 トークンとすべてのレスポンスは暗号化されずにネットワークを通過します。サーバーは ルーティング可能なアドレスで起動すると、そのことを stderr に表示します。OAuth リソースサーバーモードはありません。

ブラウザーはすべてのリクエストに Origin ヘッダーを付けて送信し、サーバーは --allowed-origins に指定されていない送信元を拒否します。ローカルの開発サーバーは どれも信頼できるとは限らないため、ループバックの送信元はデフォルトでは信頼されません。 ブラウザークライアントを実行するページを、たとえば --allowed-origins http://localhost:6274 のように指定してください。ブラウザー以外のクライアントは Origin を送信しないため、影響を受けません。

安全性

• デフォルトでは読み取り専用です。 --enable-mutations を指定すると、クローンと同期が可能になります。削除にはさらに --enable-destructive-mutations が必要です。すべての変更操作について、監査ログに意図と完了の記録が書き込まれます。
• 削除は安全側に失敗します。 MCP と CLI によるプルーニングでは、作業ツリーに変更があるリポジトリ、リモートから到達できないコミットがローカルブランチにあるリポジトリ、スタッシュ、ローカルにしかないタグや分岐したタグ、Git で無視されるコンテンツ（.env ファイル、ローカルデータベース、キャッシュなど。クローン内で最も復元しにくく、通常の git status では見えないもの）、未公開のコミットを含むサブモジュール、そもそも Git リポジトリではない対象、または Git が検証できない状態のリポジトリの削除を拒否します。拒否の際は具体的な理由が示され、監査ログに記録されます。
• パストラバーサルを防止します。 ファイルリソースの検索では、選択したリポジトリのルートと候補パスを正規化し、.. やシンボリックリンクによって兄弟リポジトリやワークスペースの外へ抜けることを防ぎます。検索、シンボルインデックス、ファイルリソースは、リポジトリにコミットされたシンボリックリンクをたどりません。
• 削除には呼び出しごとの承認が必要です。 --enable-destructive-mutations を指定すると、削除を実行する前に、MCP のエリシテーションを通じて、削除ごとに人間へ確認を求めます。上記の拒否処理の連鎖は「誤り」を防ぎます。一方、どんなにプロンプトに注意書きを加えても防げない、すべてのチェックを通過した唯一のクローンを、説得されたエージェントが選ぶ事態を防ぐのがこの確認です。失っても構わない無人のワークスペースでのみ、--no-confirm-deletes を指定してください。
• デフォルトは stdio、そうでない場合はループバックです。 --transport を指定しない場合、サーバーにはエンドポイントもリスニングポートもなく、起動した親プロセスとのみ通信します。--transport streamable-http および --transport sse を指定すると、--host/--port でリッスンします。サーバーはルート配下のすべてのリポジトリを公開するため、--allow-remote とベアラートークン（--token-file または CORRAL_MCP_TOKEN）も指定しない限り、ループバック以外のアドレスは拒否されます。すべてのインターフェースにバインドする、誤って指定した --host 0.0.0.0 や --http :7777 では起動しません。サーバーはプレーンな HTTP で通信するため、リモートでリッスンする場合は、手前に TLS 終端プロキシが必要です。

ホスティングサービス

クローンは、次の6つのホスティングサービスに対応しています。

corralctl <owner>                                    # GitHub (default)
corralctl <owner> --forge github --forge-url https://ghe.example.com  # GitHub Enterprise Server
corralctl <group> --forge gitlab                     # GitLab
corralctl <owner> --forge codeberg                   # Codeberg
corralctl <owner> --forge gitea --forge-url https://git.example.com
corralctl <owner> --forge forgejo --forge-url https://forgejo.example.com
corralctl <workspace> --forge bitbucket                # Bitbucket Cloud

Gitea と Forgejo には単一の公開インスタンスがないため、--forge-url が必要です。GitLab と Codeberg では、それぞれのサービスがデフォルトになります。ホストを識別できる場合は、--forge-url だけで十分です。たとえば --forge-url https://codeberg.org は Codeberg を示します。

GitHub では、--forge-url に GitHub Enterprise Server のインスタンスを指定します。一覧の取得先はその /api/v3 API です。ホストを含む http または https の URL 以外は、github.com に置き換えず拒否されます。トークンは GH_ENTERPRISE_TOKEN（または GITHUB_ENTERPRISE_TOKEN）、続いて gh auth token --hostname <host> から取得します。これは gh CLI が使用するものと同じ名前です。github.com のトークンが Enterprise Server に送信されることはありません。

認証情報は、各ホスティングサービスのツールがすでに使っている名前で環境変数から取得します。GITLAB_TOKEN（または CI_JOB_TOKEN）、GITEA_TOKEN／FORGEJO_TOKEN／CODEBERG_TOKEN、および BITBUCKET_TOKEN です。両方が設定されている場合は、corral 専用の CORRAL_GITLAB_TOKEN または CORRAL_FORGE_TOKEN が優先されます。GitHub では、既存の優先順位（明示的なトークン、環境変数、gh CLI の順）が維持されます。

同じトークンが、すべてのホスティングサービスで、非公開リポジトリの HTTPS クローンとプルの認証に使われます。トークンは各ホスティングサービスが想定する方法で提示されます（GitLab では oauth2、Bitbucket では x-token-auth、Gitea 系ではトークンをパスワードとして使用します）。トークンはそのホスティングサービス自身の HTTPS オリジンにのみ送信され、通常の http:// 経由で送信されることはありません。

--forge は、ホスティングサービスと通信するすべての操作に適用されます。 corralctl <owner>、plan、profile、prune が対象です。孤立リポジトリの検出と prune では、一覧の取得元であるホスティングサービスと照合し、ホストごとに範囲を限定します。同じオーナー名の GitLab クローンが GitHub の孤立リポジトリと判定されることはありません。

プロファイルごとにホスティングサービスを指定できるため、1つの設定で複数のサービス上のオーナーを扱えます。

{
  "profiles": {
    "work":     { "owners": ["acme"],   "settings": { "forge": "gitlab" } },
    "personal": { "owners": ["me"] },
    "upstream": { "owners": ["forgejo"], "settings": { "forge": "codeberg" } }
  }
}

読み取りは、これまでホストに依存したことがありません。 インデックス、MCP サーバー、シンボル検索、コンテンツ検索はクローン上で動作するため、どこからでも手動でクローンしたリポジトリは、以前から第一級の対象です。

別のツールからの移行

移行ガイドは docs/migrating/ にあります。ghq からの移行、手書きのクローンスクリプトからの移行、単一リポジトリ用のコードインデックスからの移行、または整理されていない ~/src からの移行をご覧ください。

各ガイドでは、引き継がれるもの、本当に異なるもの、corral が行わないことを説明しています。どのガイドでもリポジトリの再クローンは不要です。また、corralctl plan を実行すれば、変更前に結果を確認できます。

リポジトリ横断のシンボル検索

すべてのコードコンテキストサーバーは、エージェントが開いているリポジトリ内でシンボルが定義されている場所を教えられます。corralctl だけは、マシン上のすべてのクローンを横断して回答できます。それらがすべて存在することを把握しているのが、corralctl だけだからです。

// corral_find_symbol { "name": "CanonicalRemote" }
{
  "query": "CanonicalRemote",
  "repositories_search": 2,
  "total_matched": 1,
  "symbols": [
    {
      "repo": "Public/go/corral",
      "symbol": "CanonicalRemote",
      "kind": "func",
      "file": "internal/git/git.go",
      "line": 266,
      "exported": true,
      "language": "go"
    }
  ]
}

kind（func、method、type、interface、const、var）で絞り込み、repo を指定して対象を1つのリポジトリに限定し、substring で一致させるか、exported_only を指定してエクスポート対象に絞り込めます。メソッドは名前だけ、または Receiver.Name で検索できます。テスト宣言はデフォルトで除外されます。十分なテストがあるリポジトリでは、ほかの宣言より数が多くなるためです。include_tests を指定すると、テスト宣言も検索対象になります。

corral_repo_overview は1回の呼び出しで、1つのリポジトリの概要をまとめて返します。取得元、ファイル数、種類別の宣言数、そして特に重要なエクスポート済みの型や関数が含まれます。ファイルを読む前に活用してください。

corral_search_code は corral_find_symbol に対応する機能です。find_symbol が何かが 宣言されている 場所を答えるのに対し、search_code はそれが 記述されている 場所、つまり呼び出し箇所、設定キー、チケットに記載されたエラー文字列などを検索します。デフォルトではリテラル検索で、RE2 を使う場合は regex を指定します。また、repo、language、path_glob で範囲を絞り込めます。

検索対象は、ファイルリソースが提供するファイルに限られます。そうしないと、検索を使って拒否されたファイルを1行ずつ読み取れてしまうため、認証情報ファイルが検索結果に含まれることはありません。include_tests を指定しない限り、テストファイルは除外されます。また、上限に達した場合はその旨を明示し、部分的な結果を完全な回答として提示することはありません。

インデックス対象言語：Go、Python、TypeScript、JavaScript、Rust。

Go は go/ast で解析します。これはコンパイラー自体のパーサーなので、インデックスは言語の仕様に沿ったものになります。ほかの言語は、ctags の方式に倣った行スキャナーで読み取ります。構文木を構築するのではなく、宣言構文を認識します。これらの言語向けの成熟したパーサーは、いずれも CGO（tree-sitter）を使うか、言語の進化に追いついていない移植版であるか、corral 自体より大きいためです。ここで CGO を利用できない理由は ADR-0006 に記録されています。

スキャナーは、コメントと文字列の 内容 を空白に置き換えたソースを走査します。そのため、ドキュメント文字列内の class や、テンプレートリテラル内の function は認識されません。

抽出したシンボルは $XDG_CACHE_HOME/corral/symbols にキャッシュされるため、セッションで最初の検索だけが遅くなることはありません。キャッシュがヒットしてもリポジトリの走査は行われます。走査によってキャッシュエントリーのキーとなるフィンガープリントを生成するため、編集されたクローンに古い結果が返されることはありません。--symbol-cache off でキャッシュを無効にでき、--symbol-cache <dir> で保存先を変更できます。

実際の187リポジトリのワークスペースでは、リポジトリ横断検索が 6.9秒から1.3秒 に短縮されました。短縮の大部分は、リポジトリを順番にではなく並行して検索したことによるもので、残りはキャッシュによるものです。この機能では型を解決したり、マクロを展開したり、通常とは異なる形で複数行に分割された宣言を追跡したりすることはできません。また、誤りの影響は小さく抑えられています。シンボルを見落とした場合はファイルの読み取りに戻り、誤検出があった場合は正しいファイル内の誤った行を示すだけです。存在しないシンボルを作り出すことはありません。

使用方法とフラグ

位置引数

corralctl <owner> [base_dir] [limit]

• <owner> — GitHub のユーザー名または組織名（必須）。
• [base_dir] — リポジトリの保存先となるルートディレクトリ（デフォルト：$HOME/Code）。
• [limit] — 取得するリポジトリの最大数（デフォルト：1000）。

コマンドオプション

診断情報

結果は、--output で選択した形式で stdout に出力されます。診断情報（スキップした内容、回避した問題、その理由）は stderr に出力されるため、実行時にどれほど多くの情報が出力されても、--output json の出力をパイプで扱えます。

--log-level で stderr に出力する情報量を制御できます。CORRAL_LOG_LEVEL を設定すると、シェルセッション全体に同じ設定が適用されます。

# Why did that repository not migrate? Turn the detail up.
corralctl sebastienrousseau --log-level debug

# Machine-readable results, quiet stderr, both at once.
corralctl sebastienrousseau --output json --log-level error > repos.json

# For a bug report: full detail, everything captured.
CORRAL_LOG_LEVEL=debug corralctl sebastienrousseau > out.json 2> diagnostics.log

デフォルトの info は、corral がこれまで常に出力してきた設定です。

同期オプション

corralctl sync [base_dir] は、永続的な --base-dir、--dry-run、--log-level フラグに加えて、次のオプションを受け取ります。

運用コマンド

corralctl status --base-dir ~/Code
corralctl doctor ~/Code
corralctl doctor ~/Code --refresh-tags
corralctl doctor ~/Code --prune-worktrees
corralctl doctor ~/Code --exclude winget-pkgs --timeout 30s
corralctl plan sebastienrousseau --base-dir ~/Code
corralctl prune sebastienrousseau --base-dir ~/Code --dry-run
corralctl prune sebastienrousseau --base-dir ~/Code --yes
corralctl adopt ~/Projects --forge github --owner sebastienrousseau

status はローカルクローンの一覧を作成し、doctor はワークスペースの健全性、ワークツリー、ディスク容量の上限、除外設定、Finder タグを監査します。また、中断された corral_delete_repo が残した .corral-deleting-* ディレクトリを一覧表示します（削除は行いません。内容を確認してから削除するか、元の名前に戻してください）。plan は変更を加えずに調整内容を出力し、prune は未公開作業のチェックに合格した、上流に存在しないクローンのみを削除します。adopt は追跡されていないローカルリポジトリを検出し、移動してリモートフォージにリンクします。各コマンドで JSON 出力を利用できます。

複数オーナーのプロファイルでは、厳格な JSON 設定ファイル（デフォルトは ~/.config/corral/config.json）を使用し、corralctl profile <name> で実行します。

{
  "profiles": {
    "work": {
      "owners": ["org-one", "org-two"],
      "base_dir": "/home/me/Code",
      "layout": "{{.Owner}}/{{.Visibility}}/{{.Language}}/{{.Name}}",
      "concurrency": 4
    }
  }
}

使用例

パッケージのレイアウトを確認し、corralctl モジュールをプログラムから実行するには、examples ディレクトリにある、単独で動作しコピー＆ペーストして使える Go コードの使用例をご覧ください。

1. 対話型セレクター — 選択チェックリストの TUI を AltScreen モードでプログラムから設定して起動します。
2. GitHub リポジトリの取得 — github.FetchReposWithOptions を使い、スター数による並べ替えと言語の条件を指定して GitHub REST API にクエリを送信します。
3. Git の同期 — git ヘルパーパッケージを呼び出して、クローンの実行、ブランチの照会、origin URL の解決を行います。
4. エンジンオーケストレーター — コアエンジンの engine.Run を統合し、カスタムフィルター、レイアウト構造、ドライランによる事前チェックを使ってリポジトリの同期を実行します。

トラブルシューティング

よくある質問

• GitLab やその他のホストでも使えますか？
  はい。corralctl は、GitHub、GitLab、Gitea、Forgejo、Codeberg、Bitbucket の 6 つの主要な Git ホスティングサービスと連携します。
• リモートのホスティングサービスで削除されたリポジトリはどうなりますか？
  通常の調整処理で削除されることはありません。--orphans で報告され、明示的な prune コマンドを実行すると、--yes による確認後に安全性が検証された孤立リポジトリを削除できます。
• Cron や systemd タイマーの中で実行できますか？
  はい。このコマンドはデフォルトで非対話型で実行されます。自動ジョブが停止しないよう、すべての Git コマンドで認証情報の入力プロンプトを回避します。
• 主要な言語が設定されていないリポジトリはどのように保存されますか？
  デフォルトで Other/ エコシステムカテゴリに分類されます（例：Public/Other/my-repo）。

設計者 ᛫ Sebastien Rousseau
エンジン ᛞ EUXIS ᛫ Enterprise Unified Execution Intelligence System

ドキュメント

インストール後はオフラインで man corralctl を利用でき、各サブコマンドには専用のページがあります（man corralctl-mcp）。

corralctl を使用すべきでない場合

corralctl には独自の方針があり、すべての方に合うわけではありません。

• 完全なミラーやバックアップが必要な場合。 corralctl は、読み取りや編集に使う作業コピーをクローンします。アーカイブ目的のミラーには git clone --mirror または専用ツールを使用してください。corralctl はすべての ref を保持したり、完全なコピーを保証したりするものではありません。
• corral が一覧にないホスティングサービスが必要な場合。 GitHub、GitLab、Gitea、Forgejo、Codeberg、Bitbucket はサポートされていますが、それ以外はサポートされていません。読み取りはホスティングサービスに依存しません。どのホストからのクローンも、インデックス、MCP サーバー、シンボル検索で第一級の対象として扱われます。ただし、corralctl <owner> が対応しているのはこの 6 つだけです。
• リポジトリを現在の場所に置いておく必要がある場合。 corralctl の価値は一貫性のあるレイアウトにあり、既定ではクローンを Collection/Bucket/Name に整理します。固定パスが重要な場合は、--layout で既存のツリーに合わせるか、別のツールを使用してください。
• コードインテリジェンスが必要な場合。 MCP サーバーはすべてのクローンを対象にシンボルのインデックス作成とファイル内容の検索を行いますが、機能は限定的です。宣言から分かるのは、名前、種類、ファイル、行だけです。型の解決、参照の検索、名前の変更は行いません。これらは LSP がプロジェクトごとに行い、corral はエージェントにどのプロジェクトを開くかを伝えるレイヤーです。
• WSL なしで Windows を使う必要がある場合。 Windows 用バイナリは公開されていますが、macOS Finder のタグ機能は Windows では何もせず、macOS や Linux よりも動作確認が十分ではありません。

要件とツールチェーンの方針

Go の最低バージョンは go.mod の 1 か所だけに記載し、CI では GOTOOLCHAIN=auto を設定して、ワークフローの入力値と食い違わないようにしています。

最低バージョンを引き上げる方針。 標準ライブラリの修正や言語機能によって正当化される場合は、どのリリースでも最低バージョンを引き上げることができます。その理由は該当リリースの CHANGELOG に記録します。corralctl は ディストリビューションの LTS との互換性を約束しません。ディストリビューションのツールチェーンと最低バージョンの対応表がないまま目標を掲げるより、何も約束しない方が適切だからです。パッケージ作成者は最低バージョンが維持されていると仮定せず、バージョンを更新するたびに go.mod を確認してください。

安定性の保証

corralctl は 1.0 より前の段階にあり、SemVer に従います。1.0 までは、あらゆる変更でパッチ番号を更新します。

破壊的変更となるのは、シグネチャではなく動作です。 ディレクトリを移動・削除するツールでは、フラグや関数のシグネチャに変更がなくても、ワークスペースに対する動作の変更は破壊的変更です。具体的には、次の変更を破壊的変更として扱います。

• 既定のレイアウト、またはリポジトリをパスに対応付ける方法の変更
• --output json / ndjson の出力内容の変更（フィールドの追加を除く）
• 終了コードの変更
• 拒否から許可への変更：以前は corralctl が削除、プルーニング、移行を行わなかったケースで、実行するようになること
• 既存のクライアントが認識する MCP ツールまたはリソースの仕様の変更

フィールドの追加、既定では無効な新しいフラグの追加、新たな拒否は、破壊的変更ではありません。

非推奨期間。 非推奨となったフラグやツールは、非推奨を告知したリリースの後、少なくとも 1 回のマイナーリリースが行われるまで引き続き動作し、stderr に警告を出します。選択された出力形式を出力する stdout には警告を出しません。

セキュリティと強化

報告。 公開イシューは作成しないでください。 SECURITY.md に記載された非公開の手順に従ってください。対応の SLA も同ファイルに記載されています。

セキュリティ方針。 corralctl はユーザー自身の認証情報を使用して、ユーザー自身のマシン上で動作するため、脅威モデルで重視するのは権限境界の突破ではなく、被害範囲の限定です。詳細は docs/security-model.md をご覧ください。

• 認証情報が argv や .git/config に渡ることはありません。 forge のトークンは、その forge の HTTPS オリジン（https://github.com/、https://gitlab.com/、またはお使いのインスタンス）に限定した http.extraheader として git に渡されるため、別ホスト上のサブモジュールから参照されることはありません。クローン時のエラーでは、URL に埋め込まれた認証情報がログに記録されないよう、引数を意図的に省略しています。
• git は常に非対話モードで実行されます。 GIT_TERMINAL_PROMPT=0 などを設定しているため、無人実行時にプロンプトで停止せず、失敗します。
• 破壊的な操作は、根拠がなければ実行を拒否します。 クローンに未コミット、未プッシュ、スタッシュ済み、サブモジュール内、または gitignore 対象の作業がある場合、prune と corral_delete_repo は実行を拒否します。最後のケースでは、リモートにコピーが存在しないファイルがまさに git status に表示されないためです。
• MCP サーバーはサンドボックス化され、操作が制限されています。 パス解決では両側のシンボリックリンクを正規化し、文字列のプレフィックスではなくパスの各要素を比較します。また、シンボリックリンク経由でリポジトリ内のファイルを読み取ることはありません。書き込みツールには --enable-mutations が必要で、削除には追加のフラグが必要です。すべての変更操作は、試行前に監査ログへ記録されます。
• メモリ安全性は Go によって確保されます。どこにも CGO は使用していないため（CGO_ENABLED=0）、リリースバイナリは静的で、libc に依存しません。

ファジング。 ファジングの対象は、レイアウト評価、言語の正規化、リモート URL の解析、ルート外へのパスの逸脱を決して許さないサンドボックスチェックなど、解析とパス解決の境界です。ファジングはすべてのプッシュで、一定時間実行されます。corralctl は OSS-Fuzz に登録されていません。

サプライチェーン。 リリースは鍵不要の cosign で署名され、SLSA ビルド来歴情報と CycloneDX SBOM が含まれます。また、-trimpath とコミットに固定されたタイムスタンプを使用してビルドされるため、同じコミットからのビルドはバイト単位で一致します。すべての GitHub Actions はコミット SHA で固定され、コンテナのベースイメージはダイジェストで固定されています。govulncheck はすべてのプッシュで実行されます。

ライセンス

GNU General Public License v3.0 のもとでライセンスされています。

トップに戻る