Corral

Automatically clone and organise GitHub repositories using Finder-friendly collections, ecosystems, and metadata.

Contents

Getting started

• Install — Homebrew, Arch, source, or Docker
• Quick Start — clone and organise in one command

Features & Capabilities

• Features — structured layout, concurrency, and security
• Architecture — end-to-end flow from API fetch to per-repo dispatch
• Interactive TUI Mode — keybindings, commands, and autocomplete
• Layout Customization — Apple-style collections, ecosystems, and custom templates
• Smart Syncing — network-optimised incremental updates
• Exec Mode — concurrent batch execution of Git commands
• MCP Server — expose your local workspace to AI coding agents

Reference & Operational

• Usage & Flags — complete CLI parameter reference
• Examples — index of runnable programmatic examples
• Troubleshooting — quick solutions to common errors
• Frequently Asked Questions — design decisions and Windows/WSL support
• License

Install

mise (macOS / Linux)

mise use -g github:sebastienrousseau/corral

This installs the latest released corralctl binary and keeps it managed with the rest of your mise tools.

Homebrew (macOS / Linux)

brew install sebastienrousseau/tap/corralctl

Arch Linux (AUR)

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

Build from source

Requires Go 1.26+ and Git:

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

Platform Prerequisites

brew install go git gh

sudo apt install golang git

sudo dnf install golang git gh

Quick Start

Run Corral with an owner name (GitHub username or organization) to clone and automatically sort all repositories into a clean local directory hierarchy:

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

# Run Corral for your profile
./corralctl my-username

This converges your local directory structure into a structured mirror:

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

On macOS, Corral also writes native Finder Tags to repository folders while preserving tags you added yourself. This keeps the physical hierarchy shallow and makes Finder searches and Smart Folders useful across ecosystems.

Features

Architecture

A single run resolves git, fetches every repository concurrently from GitHub, optionally lets you pick a subset interactively, then dispatches clone / smart-sync / skip decisions across a worker pool. Smart sync consults a per-repository .corral-state.json sidecar to skip a git pull when the upstream pushed_at is unchanged.

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[GitHub 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)" --> N[git pull --rebase --autostash]
    N --> N1["+ optional submodule update<br/>(--ignore-submodule-failures)"]
    J & N1 --> O[Stamp .corral-state.json]
    O & K & M --> 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

Interactive TUI Mode

By passing the -i or --interactive flag, you can launch the selection dashboard:

./corralctl -i my-username

Keybindings

• [space] — Toggle selection of the current repository.
• [ctrl+a] — Select all currently filtered repositories.
• [ctrl+n] — Deselect all currently filtered repositories.
• [/] — Enter command / filter mode.
• [enter] — Confirm selection and begin cloning/syncing.
• [esc] — Exit the application silently.

In-Session Commands

Press / inside the TUI to enter Command Mode. Commands support prefix-based autocompletion (press [tab] or [right-arrow] to autocomplete):

• /sort <field> — Sort repositories. Fields:
  • name — Alphabetical sort by repository name.
  • language / lang — Alphabetical sort by language.
  • visibility / vis — Alphabetical sort by visibility (Private/Public).
  • public — Prioritize public repositories at the top.
  • private — Prioritize private repositories at the top.
• /all — Select all filtered repositories.
• /none — Deselect all filtered repositories.
• /exit / /quit — Cancel and exit silently.
• /help — Display the in-session help panel overlay.

Layout Customization

By default, Corral uses the Apple-style layout {{.Collection}}/{{.Bucket}}/{{.Name}}. Forks use the Forks collection, while .github.io repositories use the Web bucket regardless of their detected language. You can override this using the --layout flag:

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

Supported placeholders:

• {{.Owner}} — GitHub owner name.
• {{.Name}} — Repository name.
• {{.Collection}} — Canonical root (Public, Private, or Forks).
• {{.Bucket}} — Finder-facing ecosystem bucket (Go, Rust, Web, etc.).
• {{.Language}} — Primary language normalized to lowercase.
• {{.Visibility}} — Repository visibility normalized to lowercase.

Finder Tags on macOS

Finder tagging is enabled by default on macOS and can be disabled with --finder-tags=false. Corral manages the following lifecycle taxonomy:

Uncolored metadata tags include Visibility: Public, Collection: Forks, Ecosystem: Rust, Owner: example, GitHub, Fork, Archived, Template, and Mirror. Finder can combine these tags in searches or saved Smart Folders.

Smart Syncing

Corral stores synchronization metadata next to each repository's .git/ folder inside a .corral-state.json sidecar file:

• No Redundant Pulls: If the remote repository has not received new pushes since the last sync, git pull is skipped completely.
• Overrides: To bypass smart checks and force Corral to perform a full git pull, pass the --force-sync flag.
• Skip Syncing entirely: Pass --no-sync to skip updates on all cloned repositories.

Exec Mode

Execute arbitrary shell commands concurrently across your organized repositories:

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

MCP Server (for AI agents)

Corral ships a Model Context Protocol server that exposes your local, Corral-organised workspace to AI coding agents — Claude Code, Cursor, Cline, Codex CLI, Aider, and anything else that speaks MCP. No network calls are made and the GitHub API is not contacted; the server is a read-only window into the clones already on disk.

Where GitHub's own MCP server covers the remote API surface (issues, PRs, search), corral-mcp covers the dimension only it can — your local mirror, organised by visibility and language, queryable without a round-trip.

Tools

• corral_list_repos — Filter local clones by visibility / language / name / sync state
• corral_find_repo — Resolve a fuzzy name to one clone (returns candidates on ambiguity)
• corral_get_repo_metadata — Full metadata for one clone, including current branch
• corral_status_summary — Workspace summary: counts by visibility and language
• corral_workspace_index — Full structured index in a single call

Write tools (v0.0.12, opt-in via --enable-mutations):

• corral_sync_repo — Runs git pull --rebase --autostash against one clone
• corral_clone_repo — Clones a URL into a sandboxed target path
• corral_delete_repo — Removes a clone. Requires --enable-destructive-mutations. Refuses on uncommitted/unpushed changes

Every mutation writes a JSONL audit record to $XDG_STATE_HOME/corral/mutations.log (or ~/.local/state/corral/mutations.log) capturing tool, target, args, result, and timestamp.

Prompts (v0.0.12)

• explain_workspace — Ask the agent to survey the workspace via read-only tools and summarise it
• identify_stale_repos — Ask the agent to find clones whose .corral-state.json says they haven't been synced recently (default: 30 days)

Resources

• corral://workspace/index
• corral://repo/{owner}/{name}/state
• corral://repo/{owner}/{name}/tree
• corral://repo/{owner}/{name}/file/{path} (bounded at 1 MiB; path-traversal protected)

Install

Claude Code:

claude mcp add corral -- corralctl mcp

Cursor / Cline (mcp.json):

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

Docker (no local install required) — the same binary the MCP Registry advertises, mounted against your workspace:

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

Notes on the args:

• --user 1000:1000 — replace with your host UID:GID (id -u:id -g) so the containerised scanner reads the mounted workspace with the same permissions your host user has. Without this the image runs as a system UID inside the container and hits permission denied on any directory your workspace makes group- or user-private.
• -v … :ro — read-only mount. The v0 tools are read-only anyway; mounting :ro documents that and defends against a hostile agent asking the server for a write it doesn't have.
• --root /workspace — sandbox root inside the container. Every tool and resource path check is scoped to this prefix; requests outside it are rejected regardless of what the agent asks for.

Sandbox a different root (defaults to --base-dir, then $HOME/Code):

corralctl mcp --root /custom/workspace

Safety

• Read-only by default. --enable-mutations unlocks clone and sync. Deletion additionally requires --enable-destructive-mutations; every mutation writes intent and completion records to the audit log.
• Deletion fails closed. MCP and CLI pruning refuse repositories with working-tree changes, commits on any local branch not reachable from a remote, stashes, unpublished tags, or unverifiable Git state.
• Path-traversal protected. File-resource lookups canonicalise the selected repository root and candidate path, blocking .. and symlink escapes into sibling repositories or outside the workspace.
• stdio-only. No HTTP endpoint, no listening port — the server only ever speaks to the parent process that launched it.

Usage & Flags

Positional Arguments

corralctl <owner> [base_dir] [limit]

• <owner> — GitHub username or organization (Required).
• [base_dir] — Root directory to save repositories (Default: $HOME/Code).
• [limit] — Maximum repositories to fetch (Default: 1000).

Command Options

Operational Commands

corralctl status --base-dir ~/Code
corralctl plan sebastienrousseau --base-dir ~/Code
corralctl prune sebastienrousseau --base-dir ~/Code --dry-run
corralctl prune sebastienrousseau --base-dir ~/Code --yes

status inventories local clones, plan emits a non-mutating reconciliation, and prune removes only upstream-orphaned clones that pass the unpublished-work checks. JSON output is available on each command.

Multi-owner profiles use a strict JSON config (default ~/.config/corral/config.json) and run with corralctl profile <name>:

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

Examples

To inspect the package layout and programmatically run Corral modules, see the self-contained, copy-pasteable Go code examples in the examples directory:

1. Interactive Selector — Programmatically configure and launch the selection checklist TUI in AltScreen mode.
2. GitHub Repository Fetcher — Query the GitHub REST API using github.FetchReposWithOptions with stars sorting and language constraints.
3. Git Syncing — Call the git helper package to perform clones, query branches, and resolve origin URLs.
4. Engine Orchestrator — Integrate the core engine engine.Run to run repository syncing with custom filters, layout structures, and dry-run pre-flights.

Troubleshooting

Frequently Asked Questions

• Does it work with GitLab or other hosts?
  No. Corral is specifically built to integrate with the GitHub API and GitHub CLI (gh).
• What happens to repositories deleted on GitHub?
  Normal reconciliation never deletes them. --orphans reports them; the explicit prune command can remove verified-safe orphans after --yes confirmation.
• Can I run it inside Cron or systemd timers?
  Yes. The command runs non-interactively by default. All Git command credential prompts are bypassed to ensure automated jobs never hang.
• How are repositories with no primary language stored?
  They default to the Other/ ecosystem category (e.g. Public/Other/my-repo).

THE ARCHITECT ᛫ Sebastien Rousseau
THE ENGINE ᛞ EUXIS ᛫ Enterprise Unified Execution Intelligence System

License

Licensed under the GNU General Public License v3.0.

Back to Top