Skip to content

Start Here

Follow this path when you want Shoal installed quickly and you want the next branching docs choices to stay obvious.

Getting Started

This path is optimized for a developer who wants Shoal working quickly. It defines the core terms you need to know, guides you through installation, and gets your first sessions running.

Core Concepts

Before you start, understand the pieces Shoal connects:

  • Worktree: A Git worktree. Shoal gives each agent its own isolated branch and filesystem so they can work in parallel without overwriting your current checked-out state.
  • Pane/Session: A tmux construct. Shoal uses tmux to persist agent shells. You can attach, detach, and survive network drops.
  • MCP (Model Context Protocol): The standard that lets Shoal expose context and tools to agents. The shoal-orchestrator MCP server lets one agent inspect or control others.
  • Template: A declarative configuration for a session (which shell to use, which tools to attach, what to run on startup).
  • Fin: A lightweight protocol for passing initialization data or contracts to an agent when it starts.
Check the toolchain

Confirm uv, tmux, and git are available before you start layering templates and shells.

Install the CLI

Run pipx install shoal-cli or uv tool install shoal-cli. With MCP support: uv tool install "shoal-cli[mcp]".

Initialize the control plane

Run shoal init and shoal setup fish to scaffold state, config, and the intended shell ergonomics.

Launch and supervise

Create the first worktrees, then use shoal status, shoal popup, and shoal attach to operate them.

MCP support

The [mcp] extra activates the shoal-orchestrator MCP server, which lets other AI agents create, inspect, and kill sessions directly — no shell access required.

uv tool install "shoal-cli[mcp]"

Prerequisites

Shoal assumes a terminal-centric workflow and relies on a small set of system tools.

Tool Why it matters
uv Installs Shoal and manages the Python environment
tmux Runs each agent in an isolated session or pane
git Creates worktrees and branches safely
fish Recommended reference shell for completions, key bindings, and helper functions
fzf Enables interactive selection in commands like shoal attach
Optional tools
  • gh for shoal wt finish --pr
  • nvr for Neovim integration

Install

pipx install shoal-cli

# or with uv
uv tool install shoal-cli

# With MCP support (enables shoal-orchestrator MCP server)
uv tool install "shoal-cli[mcp]"

Via Homebrew (macOS)

brew install TheShoal/tap/shoal-cli

This installs a self-contained binary — no Python environment required.

Direct binary download

Download a self-contained binary from the latest release:

Platform Asset
macOS arm64 (Apple Silicon) shoal-darwin-arm64
macOS x86_64 (Intel) shoal-darwin-x86_64
Linux x86_64 shoal-linux-x86_64 
# Example: macOS Apple Silicon
curl -Lo shoal https://github.com/TheShoal/shoal-cli/releases/latest/download/shoal-darwin-arm64
chmod +x shoal
sudo mv shoal /usr/local/bin/

From source for development

git clone https://github.com/TheShoal/shoal-cli.git
cd shoal-cli
uv tool install -e ".[dev,mcp]"
uv tool install pre-commit
just setup

Initialize Shoal

shoal init
shoal setup fish

First run

If shoal init reports missing tools, fix them before running shoal setup fish. The fish integration assumes the state directories exist.

shoal init creates the XDG config, state, and runtime directories, scaffolds bundled tool and template files, and checks the local environment. shoal setup fish installs the interactive shell integration on top of that baseline.

Launch your first sessions

shoal new -t claude -w auth -b
shoal new -t omp -w api-refactor -b
shoal new -t omp -w docs-refresh -b

What those flags do:

  • -t selects the tool profile.
  • -w names the worktree and session.
  • -b creates a dedicated branch automatically. When the template specifies [template.git] branch_prefix, that prefix replaces the default feat/ category (e.g. branch_prefix = "fix" → fix/<worktree>). See Local Templates — Per-Session Git Identity.

Check the fleet

shoal status
shoal popup
shoal attach auth
shoal ls --tree

Use shoal status for a fast summary, shoal popup for the interactive dashboard, and shoal attach when you need to drop into a specific session directly.

The supervision loop

Read it left to right: sessions run in the background, and you stay in flow through status and popup instead of manually watching each pane.

flowchart LR
    Create["shoal new"] --> Sessions["tmux sessions\nworktrees + state"]
    Sessions --> Status["shoal status"]
    Status --> Popup["shoal popup"]
    Popup -->|"approve / redirect"| Sessions
    Popup -->|"attach"| Sessions

Common next steps

CLI Reference See the top-level commands, subcommands, and the workflows they support. System Architecture Understand the core services, isolation models, and atomic rollbacks. Better shell ergonomics Learn patterns for agent momentum and flow-state workflows.
  • Git identity per session: Use [template.git] in your template to scope user.name, user.email, and commit template to each worktree. Set branch_prefix to control the default branch category for shoal new -b. See Local Templates — Per-Session Git Identity.