The Problem

squad is a multi-agent terminal collaboration tool where AI CLI agents communicate through SQLite. Teams of agents (manager, worker, inspector) coordinate via /squad commands in individual terminals. The codebase shows deep code health issues that increase cognitive load for anyone modifying the system: four files have max indentation depth of 11, making control flow hard to follow, and 32 repeated 6-line blocks appear across six files, violating DRY principles. The largest file contains 1,230 lines of code, meaning any change ripples widely through the codebase.

What This Does

squad provides a CLI for multi-agent collaboration through simple commands. The repository contains 54 files across Rust source, tests, documentation, and scripts. Core functionality lives in src/main.rs (50 functions, 6 type definitions), src/store.rs (34 functions handling database operations), and src/init.rs (workspace initialization). The entry point main at src/main.rs:16 reaches 98 functions, serving as the program's root. Configuration and installation instructions appear in README.md; Homebrew install uses mco-org/tap/squad, Windows uses GitHub Releases binaries, and building from source uses cargo install --git https://github.com/mco-org/squad.git. The squad setup command initializes the environment, and squad init creates a workspace.

How It Is Wired

Execution starts at src/main.rs:16 (main), which reaches 98 functions and is called by nothing else in the repo. From main, control flows to command handlers: cmd_init at line 586 reaches 16 functions and calls init_workspace_with_options → append_if_missing (filesystem via std::fs::OpenOptions::new().create(true)). cmd_send at line 706 reaches 19 functions and calls list_agents (database via self.conn.prepare). cmd_receive at line 786 reaches 18 functions. The most central function is squad, called from 67 places; register_agent from 24 places; find_workspace from 17 places. src/store.rs is called from 4 other files and reads/writes both files and a database; its open, register_agent, and register_agent_with_metadata are key touchpoints. The internal call graph has 442 resolved call edges. tests/cli_test.rs has the widest reach: 66 functions, called from 1 other file, calls into 2, and reads/writes both files and a database. src/store.rs has blast radius: any change to its 34 functions affects database persistence across the system. Four files suffer deep nesting (max indentation depth 11), and three files have high branching density (35 branch points over 87 lines in src/init.rs, src/session.rs, src/store.rs).

How To Use It

Setup:

  • Install via Homebrew: brew install mco-org/tap/squad
  • Or build from source: cargo install --git https://github.com/mco-org/squad.git
  • Or download prebuilt binary from GitHub Releases

Configuration:

  • No environment variables or config files are required for basic operation; workspace is initialized locally

Running it:

  • squad setup – initializes the environment
  • squad init – initializes workspace in your project
  • /squad manager – in terminal 1 (assigns manager role)
  • /squad worker – in terminal 2 (enters work loop, checks for messages)
  • /squad inspector – in terminal 3 (monitors state)

Optional tmux launcher: scripts/squad-tmux-launch.sh /path/to/project --dry-run reads .squad/launcher.yaml and .squad/run-task.md, generates prompt files, and starts a tiled tmux session with agents injected into Claude panes. Requirements: tmux, ruby.

Real-World Use

A team of three AI agents divides labor on a codebase: the manager agent receives a goal via /squad manager, decomposes it into tasks, and assigns them to worker agents via /squad worker. Each worker reads its role instructions, processes the task, and replies through SQLite. The inspector monitors message history. For example, a manager might run /squad worker implement auth login flow, and the worker agent completes the implementation, then signals completion. The manager tracks progress without polling—agents push messages to the shared database, and the manager's work loop picks up new tasks automatically.

Code Health & Issues

The static analysis found 12 issues across 4 kinds:

  • [HIGH/cognitive_load] Deep nesting x4 – src/main.rs, src/setup.rs, src/store.rs; max indentation depth 11 makes control flow hard to follow. Fix: flatten with early returns/guard clauses; extract inner blocks.
  • [HIGH/clarity] Duplicated code blocks – 32 repeated 6-line blocks across Formula/squad.rb, docs/homebrew-tap/Formula/squad.rb, src/store.rs, tests/store_test.rs. Fix: extract shared helpers; DRY the repeated logic.
  • [HIGH/cognitive_load] Oversized file x4 – src/main.rs, tests/cli_test.rs, scripts/squad-tmux-launch.sh; 1230 code lines hard to hold in one head. Fix: split into cohesive units by responsibility.
  • [MEDIUM/cognitive_load] High branching density x3 – src/init.rs, src/session.rs, src/store.rs; 35 branch points over 87 lines. Fix: decompose decision-heavy logic; consider table/strategy dispatch.

Beyond these measured findings, the SDLC observations from the hygiene block are relevant:

  • GitHub Actions not pinned to commit SHAs (dtolnay/rust-toolchain@stable)
  • GITHUB_TOKEN permissions not declared least-privilege in ci.yml
  • No Dependabot/Renovate configured; only Cargo.toml and Cargo.lock present
  • No dependency vulnerability scan gated on pull requests
  • release.yml checkout retains token (persist-credentials not set to false)

The Bottom Line

squad delivers a functional multi-agent collaboration tool with a straightforward CLI workflow, but the codebase has significant maintainability debt: oversized files, deep nesting, and duplicated blocks make changes risky and hard to reason about. The pinning and permissions gaps in CI are straightforward fixes. Teams wanting to embed coordinating AI agents through SQLite will find it functional today, but engineers should budget time to restructure the most nested and duplicated modules before depending on it for critical workflows.