The programmable multi-agent CLI for GitHub Copilot. Build an AI team, assign roles, and let them work your repo—automating issue triage, code review, documentation, and more through orchestrated AI agents.

Breaking changes are documented in CHANGELOG.md.

• Git — Squad stores team state in a repository
• GitHub Copilot CLI — provides the AI backend and is installed separately
• GitHub CLI (gh) — required only for GitHub issue, pull request, and work-loop operations

Node.js 22.5 or later is required for npm installs. The standalone methods below vendor Node.js and do not require npm or access to the npm registry.

# Global (recommended)
npm install -g @bradygaster/squad-cli@latest

# Project-local
npm install --save-dev @bradygaster/squad-cli

# Preview channel
npm install -g @bradygaster/squad-cli@preview

# Insider channel (pre-release builds)
npm install -g @bradygaster/squad-cli@insider

macOS with Homebrew:

brew tap bradygaster/squad
brew install --cask squad

# Early-release channels
brew install --cask squad-preview
brew install --cask squad-insider

Windows with WinGet:

winget install --id bradygaster.Squad --exact

# Early-release channels
winget install --id bradygaster.Squad.Preview --exact
winget install --id bradygaster.Squad.Insider --exact

Only one channel can own the squad command at a time. Uninstall the current cask or package before switching channels.

macOS or Linux with the verified install script:

curl -fsSL https://raw.githubusercontent.com/github/squad/main/scripts/install.sh | sh

You can also download the archive for your platform directly from GitHub Releases. See Standalone Install for checksums, custom install locations, and CI usage.

squad --version
squad doctor    # Validate setup

Get a working AI team in three steps:

# 1. Initialize Squad in your repo
squad init

# 2. Launch the interactive shell and talk to your team
squad

The init command creates a .squad/ directory with default agents and configuration. Then squad opens a REPL where you can chat with agents, assign work, and monitor progress.

Example:

squad > @Neo, review the authentication module
squad > Trinity, add unit tests for the login page
squad > /status    # See what's in progress

For detailed documentation on each command, see the CLI Reference on the docs site.

Run squad with no arguments to enter the REPL. You'll see:

squad >

All shell commands start with /.

Use agent names to route messages. Name matching is case-insensitive:

squad > @Neo, review the architecture
squad > @trinity fix the login bug
squad > Summarize the latest decisions

Omit the agent name and the coordinator routes to the best fit.

When you run squad init, Squad creates a .squad/ directory with this structure:

.squad/
├── team.md                # Roster — agent names, roles, human members
├── routing.md             # Work routing rules (which agent handles what)
├── decisions.md           # Architectural decisions log (append-only)
├── directives.md          # Permanent team rules and conventions
├── ceremonies.md          # Team ceremonies and rituals
├── casting-state.json     # Agent names, universe theme
├── model-config.json      # Per-agent model overrides
├── manifest.json          # Squad metadata and version
├── config.json            # Local config (teamRoot, etc.)
├── agents/                # Agent knowledge files
│   ├── neo/
│   │   ├── charter.md     # Role definition, expertise
│   │   └── history.md     # Accumulated knowledge
│   └── ...
├── skills/                # Reusable knowledge (markdown files)
│   ├── auth-rate-limiting.md
│   └── ...
└── sessions/              # Saved REPL sessions

team.md — Defines your roster:

## Team

🏗️  Neo       — Lead        Scope, decisions, code review
⚛️  Trinity   — Frontend    React, TypeScript, UI
🔧  Morpheus — Backend     Node.js, Express, databases
🧪  Tank     — Tester      Jest, integration tests

routing.md — Controls work assignment:

# Routing Rules

**Frontend changes** → Trinity
**Backend API work** → Morpheus
**Database migrations** → Morpheus
**Test writing** → Tank
**Architecture** → Neo

decisions.md — Append-only architectural log (agents read this before every task):

### 2025-03-20: Use Zod for API validation
**By:** Morpheus
**What:** All API input validation uses Zod schemas
**Why:** Type-safe, composable, generates TypeScript types

directives.md — Permanent rules agents always follow:

- Always use TypeScript strict mode
- No any/unknown casts
- All database queries through Prisma, no raw SQL

When you run squad init, Squad installs 8 curated skills into .github/skills/. These skills teach your agents best practices and conventions:

Each skill is a SKILL.md file inside .github/skills/<skill-name>/.

• squad init — Installs the 8 manifest skills on first run. If .github/skills/ already has content, init skips skill installation (idempotent).
• squad upgrade — Refreshes manifest skills to their latest versions. Skills marked overwriteOnUpgrade: true (all built-in skills) are always updated to pick up fixes and improvements.

You can add your own skills by creating a new directory under .github/skills/:

.github/skills/my-custom-skill/
└── SKILL.md

Custom skills are not overwritten during upgrade because they are not part of the built-in manifest.

Squad looks for .squad/config.json to customize behavior:

{
  "teamRoot": "./team-config",
  "maxAgents": 10,
  "modelDefaults": {
    "temperature": 0.7
  }
}

When Squad starts, it looks for .squad/ in this order:

1. Current directory (./.squad/)
2. Parent directories (walk up to project root)

First match wins. Squad never resolves a squad from your user profile: outside a project (no .squad/ in the directory tree) state commands such as squad status, squad doctor and squad cast fail with No squad in this directory — run squad init in the project first.

When something isn't working, run:

squad doctor

This performs a comprehensive diagnostic check:

• .squad/ directory structure
• Required files: team.md, routing.md, decisions.md
• Agent directory and count
• Configuration validity
• Team root resolution (remote mode)

Example output:

🩺 Squad Doctor
═══════════════

Mode: local

✅  .squad/ directory exists — directory present
✅  team.md found — file present
✅  routing.md found — file present
✅  agents/ directory exists (4 agents)
✅  decisions.md exists — file present

Summary: 5 passed, 0 failed

Missing .squad/ directory

Run squad init to create it.

Authentication errors

Ensure GitHub Copilot is installed and you're authenticated. Check your token:

gh auth status

Node.js version mismatch

The npm package requires Node.js 22.5 or later. Check your version:

node --version

Standalone installations vendor a compatible runtime and do not use the system Node.js installation.

ESM import errors

Squad is an ESM-only module. If you see import errors from an npm installation, ensure your Node.js version is 22.5 or later.

• Documentation: docs.squad.ai
• CLI Reference: docs.squad.ai/reference/cli — detailed command docs
• SDK: @bradygaster/squad-sdk — programmatic API
• GitHub: github.com/github/squad
• Issues: github.com/github/squad/issues

MIT. See LICENSE in the repository root.