io.github.sebastienrousseau/corral

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 — templated visibility and language organization
• 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

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 build              # compiles ./corralctl

Platform Prerequisites

brew install go git gh

sudo apt install golang git

Install gh separately following the GitHub CLI installation guide.

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/
│   └── other/
│       └── dotfiles/
└── Private/
    └── python/
        └── internal-tool/

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/>Visibility/Language/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 layout {{.Visibility}}/{{.Language}}/{{.Name}}. You can override this using the --layout flag:

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

Supported placeholders:

• {{.Owner}} — GitHub owner name.
• {{.Name}} — Repository name.
• {{.Language}} — Primary language normalized to lowercase.
• {{.Visibility}} — Repository visibility (Public or Private).

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

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

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)

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. Phase-3 write tools (corral_sync_repo, corral_clone_repo) are reserved for a follow-up release; --enable-mutations is a placeholder flag today.
• Path-traversal protected. File-resource lookups canonicalise both the configured root and the candidate path before comparison, so a malicious {path} cannot escape the sandbox via .. or symlinks.
• 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

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?
  Corral never deletes your local checkouts. To see repositories that no longer exist upstream, run Corral with the --orphans flag.
• 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/ language 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.