shoal

verb to gather and move together.

The control plane for parallel coding agents

Run a fleet of coding agents with visible state, recoverable handoffs, and human authority over every judgment call.

Shoal gives each agent its own worktree, provider-backed session runtime, state tracking, and shared MCP infrastructure — so you can supervise a parallel agent fleet from one CLI without losing visibility, authority, or flow. Parallel AI coding that feels like a controlled workflow, not a pile of threads.

Get Started Run Better Workflows

The control loop in one glance

Read it left to right: you declare work once, Shoal turns it into isolated sessions, and the resulting state flows back to one operator surface instead of scattering across tabs and terminals.

flowchart LR
    Intent["Operator intent<br/>tasks, approvals, priorities"] --> Shoal["Shoal control plane"]
    Shoal --> Templates["templates + tool profiles"]
    Shoal --> Sessions["isolated sessions<br/>runtime + worktrees + MCP"]
    Sessions --> State["status, journals, waiting prompts, errors"]
    State --> Shoal
    Shoal --> Surface["shoal status / popup / attach"]

Core Isolation: Panes & Worktrees

Shoal gives every session structural isolation. They don't block you, and they don't corrupt each other.

flowchart LR
    subgraph Operator Terminal
      A[tmux pane 0<br>you, the human]
      B[tmux pane 1<br>agent 'auth']
      C[tmux pane 2<br>agent 'api']
    end
    subgraph Filesystem
      D[/project<br>main branch]
      E[/project/.shoal/<br>status.db]
      F[/project/.worktrees/auth/]
      G[/project/.worktrees/api-refactor/]
    end
    A --> D
    B --> F
    C --> G

Each agent works in its own terminal pane bounded to a unique git worktree. If an agent ruins its files, your main check-out is unaffected. If you close your laptop, the tmux sessions stay alive and the agents keep running.

Why Shoal exists

Shoal is built for the point where "open another terminal" stops scaling.

• You want multiple AI agents working in parallel without stomping on each other's files.
• You need each agent isolated from the others at the filesystem and branch level.
• You still need one place to monitor status, approvals, errors, and MCP connectivity.
• You want recoverable handoffs — not just raw thread history — when you step away.
• You want automation hooks instead of copy-pasting the same setup into each session.

Shoal is not another coding agent

Shoal does not compete with Claude Code, Codex, Pi, Gemini, or OpenCode. It is the layer above the agent interface and runtime where supervision, state, topology, handoffs, and control live.

Think of the stack in layers: the runtime executes and enforces its own sandbox or permission model; Shoal operates above it as the operator surface. - Not a better model. Use whichever agent you want — Shoal runs them all. - Not a better editor. The terminal is the surface; Shoal makes it legible. - Not a desktop app. The control plane runs in your terminal and survives SSH, overnight runs, and remote fleets without changing the UX.

Experimental external supervisors

Shoal can now be driven by external schedulers such as Hermes over HTTP MCP. That path is real but still in development: keep it local-only, start with read-only fleet digests, and use a strict whitelist until the operator loop is proven.

The move Shoal makes: give serious developers a way to operate multiple coding agents as a coherent system instead of a growing pile of chat threads.

What Shoal is really designing

Shoal is a control plane for human-AI collaboration at the terminal.

That means secure runtimes such as OpenShell can fit cleanly underneath Shoal: Shoal can coordinate them, but runtime security stays with the runtime.

• Templates reduce setup friction before work starts.
• Tmux topology keeps multiple sessions visible and recoverable.
• Robo handles waiting-state pressure without hiding approvals.
• Journals preserve narrative memory so interruptions are cheap.
• Naming conventions turn session lists into a readable operations board.
• Remote tunnels let you operate fleets on other machines without changing the UX.

What you get

Fast start Install Shoal, scaffold config, and launch a first session in minutes. CLI map See the top-level commands, subcommands, and the workflows they support. System model Understand how runtime providers, SQLite, FastAPI, and the MCP pool fit together. Interaction design See how Shoal turns naming, topology, visibility, and approvals into a usable human loop. Robo supervision Automate approvals, routing, and escalation with a supervisor session. Flow-state patterns Design session topology, supervision loops, and shell ergonomics for momentum. Operator playbooks Adopt concrete daily patterns for triage, feature work, remote execution, and release control. Team doctrine Standardize naming, review lanes, journals, and escalation rules across the whole crew. Review checklist Give reviewer sessions a concrete risk-first contract instead of vague “look it over” work. Remote fleets Control sessions on other machines over SSH tunnels without changing the UX. Python API Browse the current configuration, state, and MCP server internals.

Sixty-second workflow

# Install once
pipx install shoal-cli

# Initialize and set up shell integration
shoal init
shoal setup fish

# Spin up three parallel agents on separate worktrees
shoal new -t claude -w auth -b
shoal new -t claude -w api-refactor -b
shoal new -t claude -w docs-refresh -b

# Supervise
shoal status
shoal popup
shoal attach auth

Operating principles

Bias toward defaulted starts Sessions should open faster than you can second-guess the setup.

Keep state visible Status, waiting prompts, and handoff context should stay one gesture away.

Name work like an operator Readable session names turn the fleet into a working board instead of a pile of panes.

Make interruption cheap Journals, templates, and role-separated sessions should preserve narrative continuity.

Keep authority human Agents should increase throughput, not silently absorb judgment calls.

Signature operating modes

Mode 01

Author, reviewer, supervisor

One agent writes, one critiques, and robo keeps the approval loop short.

Mode 02

Planner, implementer, closer

Use this when orchestration and decision sequencing matter more than raw code throughput.

Mode 03

Local control, remote execution

Keep one operator surface while sending long-running work to remote boxes and batch lanes.

Documentation map

Start here

• Getting Started for installation, initialization, and the first real session.
• CLI Reference for command groups and high-signal examples.

Operate Shoal

• Flow-State Workflows for high-leverage setups, templates, and supervision loops.
• Operator Playbooks for concrete day-to-day operating patterns.
• Team Doctrine for naming, review, and escalation rules that hold up across a team.
• Review Checklist for a reusable risk-first review contract.
• Robo Supervisor for automation patterns and escalation rules.
• Remote Sessions for SSH-backed control of remote fleets.
• Fish Integration for completions, bindings, and helper functions.
• Local Templates for project-scoped templates and mixins.
• Journals for append-only session logs and frontmatter.
• HTTP Transport for orchestrator transport details.
• Troubleshooting for failure recovery and environment fixes.

Design the loop

• Terminal Interaction Design for the operating philosophy behind naming, topology, approvals, and interruption recovery.
• Architecture for the control-plane model and design boundaries.
• Implementation Audit for a code-versus-claims review of the current product surface.

Reference

• Python API Reference for rendered module docs.
• Extensions and Extensions Review for fin boundaries and gaps.

Project records

• Contributing for development workflow and standards.
• Roadmap, Release Process, and Changelog for project planning and release history.
• Architecture Guide, Worktree Environment Init, Composition Gateway, and Transport Spike for deeper design investigations.

Build the docs site locally

just docs-serve
just docs-build