squad

squad is a Rust command-line tool that coordinates multiple AI coding-agent CLIs — Claude Code, Gemini CLI, Codex CLI, and OpenCode — working together across separate terminal sessions. Instead of running a background daemon or exposing a network API, every squad command is a one-shot operation against a local SQLite database (.squad/messages.db): an agent joins with squad join, checks for work with squad receive, and reports back with squad task complete, all through plain shell invocations.

Around that shared database, squad layers a lightweight coordination model: role templates (manager, worker, inspector, or custom markdown roles) define how an agent should behave once it joins, a task table tracks queued/acked/completed state with lease-based ownership, and automatic ID suffixing (worker, worker-2, worker-3) lets several agents take the same role without collisions. squad setup installs a /squad slash command into each supported AI CLI’s own command directory, so starting collaboration is as simple as typing /squad manager in one terminal and /squad worker in another.

An optional tmux launcher script (scripts/squad-tmux-launch.sh) automates the human side further — reading a task brief and launcher config, tiling a tmux session, and injecting the right /squad commands into each pane, optionally inside an isolated git worktree. The core CLI itself stays dependency-light and cross-platform, distributed as prebuilt binaries for macOS, Linux, and Windows, via a Homebrew tap, or built from source with Cargo.

What You Get

• A squad CLI binary with join/leave/send/receive/task/history commands operating on a local SQLite store
• Built-in manager, worker, and inspector role templates (plus support for fully custom markdown roles)
• A task lifecycle (create → ack → complete/requeue) with lease-based ownership so tasks don’t get double-claimed
• One-command /squad slash-command installation for Claude Code, Gemini CLI, Codex CLI, and OpenCode
• Automatic agent ID conflict resolution (worker, worker-2, worker-3) so duplicate roles just work
• An optional tmux launcher script that tiles a multi-pane session and injects /squad commands automatically

Common Use Cases

• Running a manager agent that decomposes a feature request into tasks for several worker agents in parallel terminals
• Mixing AI CLI vendors in one workflow — e.g. Claude Code as manager and Codex CLI as a worker — since coordination happens through shell commands, not vendor APIs
• Adding an inspector agent that reviews completed work before it’s merged, without giving it write access to the task queue
• Scripting unattended multi-agent runs via squad receive --wait and squad task complete --summary, since every command is non-interactive and stateless

Under The Hood

Architecture squad is a thin CLI dispatcher (src/main.rs, ~1,300 lines) that parses subcommands and delegates to focused modules: store.rs owns all SQLite persistence (agents, messages, tasks) behind a Store struct opened fresh on every invocation with WAL journaling and a busy-timeout, session.rs writes and validates per-agent token files to detect when a second terminal steals an agent ID, roles.rs resolves builtin or custom markdown role prompts, teams.rs loads YAML team templates, and setup.rs installs the platform-specific /squad slash-command file for each supported AI CLI. There is no long-running process anywhere in the design — every command opens the database, performs one operation, and exits, so the entire coordination protocol lives in SQLite’s own row-level locking plus additive, ignore-on-conflict ALTER TABLE migrations that keep older .squad/messages.db files forward-compatible.

Tech Stack The CLI is built in Rust (2021 edition) on rusqlite with the bundled feature, so it ships its own SQLite and needs no system library. serde/serde_json/serde_yaml handle role and team template serialization, chrono manages timestamps, uuid generates task IDs, fs2 provides advisory file locking for session tokens, and anyhow supplies contextual error handling throughout. Distribution covers a Homebrew tap, prebuilt GitHub Release binaries for four platforms, and cargo install --git from source; an optional bash-and-tmux launcher script (requiring ruby to parse its YAML config) automates spinning up a tiled multi-terminal session.

Code Quality The test suite is unusually extensive for a project this size — eleven test files totaling more lines than the entire src/ directory, with roughly 157 #[test] functions covering the CLI end-to-end via assert_cmd/predicates plus focused unit tests on the store, session, roles, and teams modules. CI runs on a three-OS matrix (Ubuntu, macOS, Windows) and gates every push on cargo fmt --check, cargo clippy --all-targets --all-features -- -D warnings, cargo test --all, and shell smoke tests for the tmux launcher. Errors are handled consistently through typed anyhow::Result with contextual .with_context() messages rather than silent unwraps or swallowed failures.

What Makes It Unique Rather than building a new orchestration framework or requiring agents to speak a custom protocol, squad’s core bet is that coordinating several independent AI CLI processes doesn’t need a server at all — a shared SQLite file, opened and closed on every command, is enough to get message passing, task queues, lease-based task ownership, and session-hijack detection, all while staying invisible to the AI agent itself (which just runs the /squad slash command its own CLI already understands). That lets genuinely different AI CLI vendors participate in the same working session without any of them needing native support for multi-agent collaboration.

Self-Hosting

Licensing Model MIT licensed — all features, including multi-agent coordination, task management, and the setup/launcher tooling, are available with no license keys, paid tiers, or self-hosting restrictions of any kind.

Self-Hosting Restrictions None. squad has no hosted or cloud offering to compare against — the CLI and its SQLite-backed workspace run entirely on the user’s own machine by design.

Enterprise Features Not applicable. There is no separate paid or enterprise edition; the GitHub repository, Homebrew tap, and release binaries all ship the identical, fully-featured CLI.

License Key Required No. squad never phones home or checks a license.