Choose your interface

⚠️ Experimental — Squad is alpha software. APIs, commands, and behavior may change between releases.

Squad works across multiple interfaces. Pick the one that fits your workflow.

Try this:

# Day-to-day work with your squad
copilot --agent squad

# Setup and diagnostics
squad init
squad doctor

What are the ways to use Squad?

Squad runs in multiple modes and across multiple platforms:

GitHub Copilot CLI (`copilot` command)

The conversational terminal interface. Powered by the GitHub Copilot CLI, this is the recommended way to work with Squad day-to-day.

copilot --agent squad

Reads .squad/ and uses squad.agent.md to coordinate your team. Full feature set — sub-agent spawning, per-spawn model selection, background execution, SQL tools, parallel fan-out.

VS Code (GitHub Copilot in the editor)

Squad works identically in VS Code through GitHub Copilot. Same .squad/ directory, same agents, same decisions. Full file access, parallel execution, MCP tool inheritance. See Squad in VS Code for details.

Squad CLI (`squad` command)

The Squad CLI provides setup, diagnostics, and automation commands. Not conversational — use this for installation, validation, and operational tasks.

# Setup
squad init

# Validation
squad doctor

# Monitoring
squad watch

# Observability
squad aspire

See CLI Reference for all commands.

Interactive shell (`squad start` / `squad shell`)

⚠️ Deprecated: The interactive shell is no longer recommended. Use GitHub Copilot CLI instead for a richer agent experience.
copilot --agent squad

REPL mode for conversational interaction directly via the Squad CLI. Enter squad with no arguments to start a persistent shell session.

SDK (`@bradygaster/squad-sdk`)

Programmatic access for building tools on top of Squad. Typed APIs, routing config, agent lifecycle hooks.

npm install @bradygaster/squad-sdk

import { resolveSquad, loadConfig, SquadCoordinator } from '@bradygaster/squad-sdk';

See SDK Reference for the complete API.

Copilot Coding Agent (`@copilot`)

Autonomous GitHub bot that picks up labeled issues and opens draft PRs. Works across your entire organization without human intervention. Issue gets labeled → agent picks it up → PR gets opened → human reviews.

See Copilot Coding Agent for setup.

Which should I use?

You want to…	Use	Why
Work with your squad day-to-day	GitHub Copilot CLI or VS Code	Conversational interface, full agent spawning, parallel execution. Most natural way to collaborate with your team.
Set up Squad in a new repo	Squad CLI (`squad init`)	One command initializes `.squad/` directory and all configuration.
Check if Squad is working	Squad CLI (`squad doctor`)	Validates directory structure, agents, configuration integrity.
Monitor work 24/7	Squad CLI (`squad watch`)	Persistent polling for new issues, auto-triage, agent assignment.
View OpenTelemetry traces	Squad CLI (`squad aspire`)	Launches Aspire dashboard for observability.
Process issues autonomously	Copilot Coding Agent	GitHub Actions workflow watches for labeled issues and dispatches `@copilot`.
Build tools on top of Squad	SDK	Typed APIs, configuration loading, agent lifecycle hooks.

Feature availability matrix

Not every feature works everywhere. Here’s what’s available where:

Feature	GitHub Copilot CLI	VS Code	Squad CLI	Interactive shell	SDK
Agent spawning	✅	✅	✅	⚠️ (deprecated)	✅
Ralph / work monitoring	✅	✅	✅ (`squad watch`)	❌	✅
Per-spawn model selection	✅	⚠️ (session model only)	✅	❌	✅
Background execution	✅	⚠️ (parallel sync)	✅	❌	✅
SQL tool	✅	❌	✅	❌	✅
Aspire dashboard	❌	❌	✅	❌	❌
`squad doctor` diagnostics	❌	❌	✅	❌	✅
Issue assignment to `@copilot`	❌	❌	✅ (setup)	❌	❌

Legend:

✅ Fully supported
⚠️ Limited or constrained
❌ Not available

For a detailed breakdown of VS Code constraints and CLI parity, see Client Compatibility Matrix.

Common workflows

”I use GitHub Copilot CLI for everything”

# Terminal 1: Work with Squad
copilot --agent squad

# Let Squad call `squad` commands when needed (doctor, watch, aspire)

This is the recommended workflow. The CLI automatically invokes Squad CLI commands when needed.

”I run squad watch in one terminal and use GitHub Copilot CLI in another”

# Terminal 1: Monitoring (persistent)
squad watch --interval 10

# Terminal 2: Work with Squad
copilot --agent squad

Keep Ralph monitoring issues in the background while you work conversationally.

”I use VS Code with Copilot for coding and Squad CLI for setup”

# One-time setup
squad init
squad doctor

# Open VS Code, select Squad from agent picker
# Same .squad/ directory, same team

Initialize with CLI, work in VS Code.