Squad

Squad is a multi-agent collaboration runtime built on @github/copilot-sdk that enables developers to compose AI teams with specialized roles like Frontend, Backend, Tester, Lead, and Scribe within a code repository. It adopts a Markdown-First design where all agent state is stored as Markdown files in the .squad/ directory, shared via Git commits for cross-session memory and cross-developer collaboration.

Multi-Agent Orchestration#

• Team Composition: Create multiple specialized role agents in one repository, each with independent charter and context
• Coordinator Scheduling: Central coordinator handles message routing, task distribution, and parallel multi-agent execution
• Routing Rules: Define task-to-agent dispatch logic via routing.md

State Persistence & Collaboration#

• Markdown-First Storage: All agent state (charter, history, decisions) stored as Markdown files in .squad/ directory
• Native Git Sharing: .squad/ shared via Git commits; anyone cloning the repo gets the same team and knowledge
• Cross-Session Memory: Agent history.md accumulates project conventions and preferences across sessions
• Export/Import: squad export / squad import support portable JSON snapshots of team state

Automation & Continuous Operation#

• Ralph Watch Mode: Continuously monitors GitHub Issues and auto-dispatches to appropriate agents
• 4-Level Error Recovery: Progressive retry on execution failure
• Graceful Shutdown: --overnight-start/end for overnight pause/resume scheduling
• Multiple State Backends: --state-backend supports git-notes, orphan-branch, and in-memory persistence strategies

Context Management#

• squad nap: Context compression, trimming, and archiving to prevent context window overflow
• Branch-Switch Safety: squad externalize moves .squad/ state outside the working tree to preserve it across branch switches

Observability & Governance#

• Decision Logs: All agent decisions recorded in decisions.md, orchestration logs in orchestration-log/
• OpenTelemetry Integration: squad aspire opens Aspire dashboard
• Themed Role Naming (Casting): Unified role pool naming via casting/registry.json

Extensibility#

• Plugin Marketplace: squad plugin marketplace manages third-party plugin sources
• SDK-First Mode (Experimental): Define teams via TypeScript in squad.config.ts, squad build generates Markdown

Architecture Highlights#

Monorepo structure: packages/squad-sdk (core runtime library) + packages/squad-cli (CLI interface), managed with npm workspaces. Build and testing use TypeScript 5.7+, ESLint, Vitest (unit tests + coverage), Playwright (E2E tests), with 8 examples from beginner to advanced in the samples/ directory.

.squad/ Directory Structure#

.squad/
├── team.md              # Team roster
├── routing.md           # Routing rules
├── decisions.md         # Shared decision records
├── ceremonies.md        # Sprint ceremony configuration
├── casting/             # Role naming configuration
├── agents/{name}/       # Individual agents (charter.md + history.md)
├── skills/              # Compressed work learnings
├── identity/            # Current focus and reusable patterns
└── log/                 # Session history archive

Installation & Quick Start#

Prerequisites: Node.js ≥ 22.5.0, Git, GitHub CLI (gh)

mkdir my-project && cd my-project
git init
npm install -g @bradygaster/squad-cli
squad init
gh auth login
copilot --agent squad --yolo

VS Code method: Open Copilot Chat, select Squad Agent, then describe your project requirements.

Unconfirmed Information#

• No public standalone docs site URL; docs/ directory available via npm run docs:dev locally
• Specific minimum version of @github/copilot-sdk not declared in root package.json
• SDK-First mode marked as Experimental with known bugs
• Author Brady Gaster's specific role/organization not stated in the repository
• Plugin marketplace command exists but no actual third-party plugin sources or documentation found