squad

Squad

English | 中文

Human-led AI agent teams for any project. One command. A team that helps you move faster with your code.

Breaking changes are documented in CHANGELOG.md.

---

What is Squad?

Squad gives you a human-directed AI development team through GitHub Copilot. Describe what you're building. Get a team of specialists — frontend, backend, tester, lead — that live in your repo as files. They persist across sessions, learn your codebase, share decisions, and help you move faster without giving up oversight.

Squad is a productivity tool for humans, not a replacement for engineers, reviewers, or decision-makers. People stay accountable for priorities, approvals, and final changes; Squad helps with coordination, repetition, and parallel execution.

It's not a chatbot wearing hats. Each team member runs in its own context, reads only its own knowledge, and writes back what it learned so the work stays inspectable.

Responsible AI stance — Squad is built to amplify a human operator with GitHub Copilot, not to remove humans from the loop. Use it to delegate faster, review better, and keep governance close to the code.

---

Quick Start

1. Create your project

mkdir my-project && cd my-project
git init

✓ Validate: Run git status — you should see "No commits yet".

2. Install Squad

Choose the install method for your platform:

Method	Command
npm (all platforms, Node.js 22.5+)	npm install -g @bradygaster/squad-cli
Homebrew (macOS)	brew install --cask bradygaster/squad/squad
WinGet (Windows)	winget install --id bradygaster.Squad --exact
Install script (macOS/Linux, no npm)	See Standalone Install

Preview and insider builds are available as squad-preview and squad-insider Homebrew casks, or as bradygaster.Squad.Preview and bradygaster.Squad.Insider WinGet packages.

Direct archives for macOS, Linux, and Windows are also available from GitHub Releases.

squad init

All methods install the same CLI. Standalone installs vendor Node.js, so they do not require Node.js or access to the npm registry. See the complete installation guide for prerequisites and platform details.

⚡ Want to be up and running in under a second? Use squad init --preset default to start with a fully-configured squad — complete with members, charters, and routing rules — ready to go immediately. The default squad init (without the flag) walks you through setup step by step, ideal if you prefer to build and customize your squad deliberately.

✓ Validate: Check that .squad/team.md was created in your project.

3. Authenticate with GitHub (for Issues, PRs, and Ralph)

gh auth login

✓ Validate: Run gh auth status — you should see "Logged in to github.com".

4. Open Copilot and go

copilot --agent squad --yolo

Why --yolo? Squad makes many tool calls in a typical session. Without it, Copilot will prompt you to approve each one.

In VS Code, open Copilot Chat and select the Squad agent.

Then:

I'm starting a new project. Set up the team.
Here's what I'm building: a recipe sharing app with React and Node.

✓ Validate: Squad responds with team member proposals. Type yes to confirm — they're ready to work.

Squad proposes a team — each member named from a persistent thematic cast. You say yes. They're ready.

---

.NET package

Building a .NET app that should call a Squad team as a Microsoft Agent Framework agent? Squad.Agents.AI is a NuGet package under src/Squad.Agents.AI. Version 1.0.0 targets .NET 8, 9, and 10 and registers a Squad-backed AIAgent in DI. See the package README for installation and local validation before publication.

Upgrading

Upgrading Squad is a two-step process.

Step 1: Update the CLI binary

Use the same channel you installed from:

Installed with	Update command
npm	npm install -g @bradygaster/squad-cli@latest
Homebrew	brew upgrade --cask squad
WinGet	winget upgrade --id bradygaster.Squad --exact
Install script	Re-run the install script
Direct archive	Download the newer archive from GitHub Releases

Step 2: Update Squad-owned files in your project

squad upgrade

squad upgrade updates squad.agent.md, .github/skills, Squad workflows and .squad/templates/ to the latest versions, comparing content first so a re-run (or a CRLF checkout) changes nothing, and backing up any file you customized to <file>.local-backup before overwriting it. It never touches your .squad/ team state — your agents, decisions, and history are always preserved.

Use --force to re-apply updates even when your installed version already matches the latest.

Use Squad in other AI hosts

Squad is not tied to one client. Add --client to project the same team and the squad_state backend into Claude Code, Kiro, OpenCode, Cursor, OpenAI Codex or Google Antigravity (alongside Copilot):

squad init --client claude,opencode      # or: --client all
squad upgrade --client codex             # add a host later; refreshes every configured host

Each host gets a native coordinator file plus MCP wiring; your own settings in .mcp.json, opencode.json and the like are never clobbered. See Using Squad across clients, Squad 2.0 architecture, and the multi-client quickstart.

---

Local Development Installation

To install and run Squad from source for development:

# Clone the repository
git clone https://github.com/github/squad.git
cd squad

# Install dependencies (npm workspaces)
npm install

# Build the project (SDK first, then CLI)
npm run build

# Run the CLI directly
node ./packages/squad-cli/dist/cli-entry.js init

# Or link it globally for convenience
npm run dev:link

After npm run dev:link, the squad command will be available globally and will use your local build. To update after code changes, re-run npm run build to recompile.

---

Quick Commands

Say "squad commands" in chat to see a categorized menu of common operations — install & upgrade, team management, issues & PRs, plugins, model settings, and session state. You can also ask naturally: "how do I switch state backends?" or "how do I add a team member?" — Squad matches your intent and walks you through it. The squad-commands skill ships out of the box with every squad init and squad upgrade.

---

All Commands (17 commands)

Command	What it does
squad init	Init — scaffold Squad in the current directory (idempotent — safe to run multiple times); alias: cast; --client <list> also projects Claude Code, Kiro, OpenCode, Cursor, Codex and Antigravity; use --mode remote <path> for dual-root mode
squad upgrade	Update Squad-owned files to latest; never touches your team state; --client <list> adds hosts and refreshes every configured projection; use --migrate-directory to rename .ai-team/ → .squad/
squad upgrade --self	Update the Squad CLI package itself on its own channel (prerelease installs follow @insider, stable follows @latest); --dry-run prints the command without installing; --insider forces the prerelease channel; a downgrade is refused unless --force
squad client list	Show the client hosts configured in .squad/config.json and whether their projected files are present; squad client add <list> projects more hosts
squad update-check	Report cached CLI update status for tooling/CI; use --json for structured output, --refresh to bypass the cache
squad status	Show which squad is active and why
squad triage	Watch mode — poll for issues and auto-triage to team (aliases: watch, loop); use --interval <minutes> to set polling frequency (default: 10); with --execute dispatch Copilot agents; use --agent-cmd, --copilot-flags, --auth-user to customize agent execution; --health shows watch status; --log-file for diagnostics
squad copilot	Add/remove the Copilot coding agent (@copilot); use --off to remove, --auto-assign to enable auto-assignment
squad doctor	Check your setup and diagnose issues (alias: heartbeat)
squad link <team-repo-path>	Connect to a remote team
squad externalize	Move .squad/ state outside the working tree; survives branch switches; use --key <name> for custom project key
squad internalize	Move externalized state back into .squad/
squad shell	Deprecated — Launch interactive shell explicitly. Use copilot --agent squad instead.
squad export	Export squad to a portable JSON snapshot
squad import <file>	Import squad from an export file
squad plugin marketplace add|remove|list|browse	Manage plugin marketplaces
squad upstream add|remove|list|sync	Manage upstream Squad sources
squad nap	Context hygiene — compress, prune, archive; use --deep for aggressive compression, --dry-run to preview changes
squad aspire	Open Aspire dashboard for observability
squad scrub-emails [directory]	Remove email addresses from Squad state files (default: .squad/)

---

Watch Mode — Ralph's Automated Polling

Ralph continuously polls for work and dispatches agents to handle it. Watch mode helps a human team stay responsive — Ralph automates triage, execution handoffs, and monitoring, then escalates back to people when judgment or approval is needed.

Quick Start

# Monitor for issues (triage mode — no execution)
squad watch

# Monitor and auto-execute against actionable issues
squad watch --execute --interval 5

# With a custom agent runner that uses --task instead of -p
squad watch --execute \
  --agent-cmd "custom-agent run --task {prompt} --autopilot" \
  --auth-user myaccount

# Run watch with diagnostics
squad watch --execute --log-file ./watch.log --verbose

# Check health of running watch process
squad watch --health

Key Flags

Flag	Description
--execute	Enable agent execution (spawn Copilot sessions for actionable issues)
--interval N	Poll every N minutes (default: 10)
--agent-cmd	Custom agent command; use one standalone {prompt} token to place the prompt, or Squad appends -p <prompt>
--copilot-flags	Flags passed to the default Copilot runner (e.g., --yolo --autopilot)
--auth-user	GitHub/Azure DevOps account to use for agent auth
--log-file	Mirror output to file for later review and diagnostics
--verbose	Show extra diagnostic output (auth probes, callbacks, pulls)
--health	Show status of running watch: PID, uptime, auth readiness, capabilities
--overnight-start HH:MM	Pause watch during off-hours (e.g., --overnight-start 18:00)
--overnight-end HH:MM	Resume watch at this time (e.g., --overnight-end 08:00)
--notify-level	Control output verbosity (all / important / none, default: important)
--state-backend	Persistence strategy (git-notes or orphan-branch, default: in-memory)

How Watch Decides What to Execute

Ralph uses an agent-delegated selection pattern:

1. Ralph scans for triage-eligible issues (unassigned, labeled, etc.)
2. Ralph builds a context snapshot: issue list, squad state, recent decisions
3. Ralph writes this context to a temp file using the -p <path> flag
4. Ralph invokes the agent with that file: gh copilot -p context.md
5. The agent decides which issue to work on and how
6. Ralph monitors execution, logs results, updates issue status

This design keeps the polling loop lean while letting agents handle issue selection automatically under the team's rules, review gates, and escalation policy.

Issue Selection & Escalation

Ralph provides a rich prompt scaffold to the agent:

## Work Context

### Available Issues (prioritized)
- #42 Urgent bug in auth (P0)
- #89 Performance review pending (P1)
- #123 Docs update (P2)

### Why These Issues Matter
...context from decision archive...

### Success Criteria
- Tests pass
- Changes match team conventions
- PR linked to issue

### When to Escalate
If blocker detected → pause, log, notify humans

Agents see full context and can decide intelligently rather than blindly executing random work.

Error Recovery (4-Tier Escalation)

Watch includes a tiered remediation strategy:

1. Tier 1 — Circuit Breaker Reset: Clear and retry
2. Tier 2 — Auth Reprobe: Re-verify credentials
3. Tier 3 — Git Pull: Update local state
4. Tier 4 — Pause 30m: Back off for human intervention

This prevents watch from spamming the same failure endlessly.

State Backends

Watch can persist its state in different ways:

# Default: in-memory (loses state on restart)
squad watch --execute

# Persist to git-notes (survives restarts, no new branches)
squad watch --execute --state-backend git-notes

# Persist to orphan branch (isolated history, easy to prune)
squad watch --execute --state-backend orphan-branch

Graceful Shutdown

To stop a running watch process gracefully:

# Create sentinel file
touch .squad/ralph-stop

# Watch will finish current round and exit cleanly
# Logs final state, cleans scratch dirs

Cleanup

Watch automatically prunes stale artifacts:

• Scratch directories older than 7 days
• Log files older than 30 days
• Orphaned orchestration state

Monitoring Watch

Check on a running watch:

squad watch --health

Output example:

Ralph Watch Status

PID: 12345
Uptime: 2h 15m
Last Poll: 2 minutes ago

Auth: Ready (account: [email protected])
Capabilities: Issue triage, PR review, ADO sync

Next Poll: 14:35 (in 3 minutes)
Round: 42 / 1200

---

Interactive Shell

⚠️ Deprecated: The interactive shell (squad with no arguments) has been deprecated. For the best Squad experience, use the GitHub Copilot CLI instead.

copilot --agent squad

See Choose your interface for current options.

Tired of typing squad followed by a command every time? Enter the interactive shell.

Entering the Shell

squad

No arguments. Just squad. You'll get a prompt:

squad >

You're now connected to your team. Talk to them.

Shell Commands

All shell commands start with /:

Command	What it does
/status	Check your team and what's happening
/history	See recent messages
/agents	List all team members
/sessions	List saved sessions
/resume <id>	Restore a past session
/version	Show version
/clear	Clear the screen
/help	Show all commands
/quit	Exit the shell (or Ctrl+C)

Talking to Agents

Use @AgentName (case-insensitive) or natural language with a comma:

squad > @Keaton, analyze the architecture of this project
squad > McManus, write a blog post about our new feature
squad > Build the login page

The coordinator routes messages to the right agents. Multiple agents can work in parallel—you'll see progress in real-time.

What the Shell Does

• Real-time visibility: See agents working, decisions being recorded, blockers as they happen
• Message routing: Describe what you need; the coordinator figures out who should do it
• Parallel execution: Multiple agents work simultaneously on independent tasks
• Session persistence: If an agent crashes, it resumes from checkpoint; you never lose context
• Decision logging: Every decision is recorded in .squad/decisions.md for the whole team to see

For more details on shell usage, see the commands table above.

Samples

Eight working examples from beginner to advanced — casting, governance, streaming, Docker. See samples/README.md.

---

Agents Work in Parallel — You Stay in Control

Squad helps one human coordinate more work at once. When you give a task, the coordinator launches every agent that can usefully start — simultaneously — while you keep priorities, review, and final decisions.

You: "Team, build the login page"

  🏗️ Lead — analyzing requirements...          ⎤
  ⚛️ Frontend — building login form...          ⎥ all launched
  🔧 Backend — setting up auth endpoints...     ⎥ in parallel
  🧪 Tester — writing test cases from spec...   ⎥
  📋 Scribe — logging everything...             ⎦

When agents finish, the coordinator records follow-up work and leaves a breadcrumb trail so you can review what happened with full context:

• decisions.md — every decision any agent made
• orchestration-log/ — what was spawned, why, and what happened
• log/ — full session history, searchable

Knowledge compounds across sessions. Every time an agent works, it writes lasting learnings to its history.md. After a few sessions, agents know your conventions, your preferences, your architecture. They stop asking questions they've already answered.

And it's all in git. Anyone who clones your repo gets the team — with all their accumulated knowledge.

Each agent gets the right model. Squad picks models quality-first by default: premium for architecture, research and review, standard for code and docs, fast for mechanical work. Opt in to the balanced or economy profile, or to the hydrafusion research preview with "modelProfile": "hydrafusion" in .squad/config.json. Per-agent selection works in the Copilot CLI and app; VS Code runs every agent on the one session model. See Model Selection.

---

What Gets Created

.squad/
├── team.md              # Roster — who's on the team
├── routing.md           # Routing — who handles what
├── decisions.md         # Shared brain — team decisions
├── ceremonies.md        # Sprint ceremonies config
├── casting/
│   ├── policy.json      # Casting configuration
│   ├── registry.json    # Persistent name registry
│   └── history.json     # Universe usage history
├── agents/
│   ├── {name}/
│   │   ├── charter.md   # Identity, expertise, voice
│   │   └── history.md   # What they know about YOUR project
│   └── scribe/
│       └── charter.md   # Silent memory manager
├── skills/              # Compressed learnings from work
├── identity/
│   ├── now.md           # Current team focus
│   └── wisdom.md        # Reusable patterns
└── log/                 # Session history (searchable archive)

Commit this folder. Your team persists. Names persist. Anyone who clones gets the team — with the same cast.

SDK-First Mode (New in Phase 1)

⚠️ Experimental. SDK-first mode is under active development and has known bugs. Use markdown-first (the default) for production teams.

Prefer TypeScript? You can define your team in code instead of markdown. Create a squad.config.ts with builder functions, run squad build, and the .squad/ files are generated automatically.

// squad.config.ts
import { defineSquad, defineTeam, defineAgent } from '@bradygaster/squad-sdk';

export default defineSquad({
  team: defineTeam({ name: 'Platform Squad', members: ['@edie', '@mcmanus'] }),
  agents: [
    defineAgent({ name: 'edie', role: 'TypeScript Engineer', model: 'claude-sonnet-5' }),
    defineAgent({ name: 'mcmanus', role: 'DevRel', model: 'claude-haiku-4.5' }),
  ],
});

Run squad build to generate all the markdown. See the SDK-First Mode Guide for full documentation.

---

Monorepo Development

Squad is a monorepo with two packages:

• @bradygaster/squad-sdk — Core runtime and library for programmable agent orchestration
• @bradygaster/squad-cli — Command-line interface that depends on the SDK

Building

# Install dependencies (npm workspaces)
npm install

# Build TypeScript to dist/
npm run build

# Build CLI bundle (dist/ + esbuild → cli.js)
npm run build:cli

# Watch mode for development
npm run dev

Testing

# Run all tests
npm test

# Watch mode
npm run test:watch

Linting

# Type check (no emit)
npm run lint

Publishing

Squad uses changesets for independent versioning across packages:

# Add a changeset
npx changeset add

# Validate changesets
npm run changeset:check

Changesets are resolved on the main branch; releases happen independently per package.

---

SDK documentation

The SDK provides programmatic control over agent orchestration — custom tools, hook pipelines, file-write guards, PII scrubbing, reviewer lockout, and event-driven monitoring.

• SDK API reference
• Custom tools and hooks guide
• Extensibility guide
• Samples — eight working examples from beginner to advanced

For SDK installation: npm install @bradygaster/squad-sdk

---

GitHub Agentic Workflows

Cast a Squad for any repo — right from a GitHub issue.

If you use GitHub Agentic Workflows, you can install Squad as a reusable workflow and manage your team with slash commands in issue comments.

Install

Squad requires GitHub Issues: slash commands are issue comments, and the merged bootstrap creates a research/proposals issue. Follow the supported seven-step quick start, which checks and enables Issues before installation when the authenticated user has repository administration permission, and stops before creating a bootstrap PR when an administrator must enable them.

set -euo pipefail

owner_repo="$(gh repo view --json nameWithOwner --jq '.nameWithOwner')"
issues_enabled="$(gh api "repos/${owner_repo}" --jq '.has_issues')"
if [ "${issues_enabled}" != "true" ]; then
  if ! gh api --method PATCH "repos/${owner_repo}" \
    -F has_issues=true --silent; then
    echo "STOP: A repository administrator must enable Settings > General > Features > Issues." >&2
    exit 1
  fi
fi

test "$(gh api "repos/${owner_repo}" --jq '.has_issues')" = "true" || {
  echo "STOP: GitHub Issues must be enabled before installing Squad workflows." >&2
  exit 1
}

SQUAD_SHA="<40-character-commit-sha>"  # explicit, maintainer-approved; never `commits/dev`
gh aw add "bradygaster/squad/workflows@${SQUAD_SHA}"
rm -f .github/skills/agentic-workflows/SKILL.md
git add -- \
  .github/aw/ \
  .github/skills/ \
  .github/workflows/ \
  .gitattributes
git commit -m "Add Squad workflow"
git push

gh aw add compiles the workflows automatically. If it reports unapproved safe-update changes, review them and run gh aw compile --approve.

Review the complete generated diff before you commit:

Path	What gh-aw writes	Commit?
.github/workflows/	The Squad workflow sources, shared imports, compiled lock files, and agentics-maintenance.yml	Yes
.github/aw/	Supporting gh-aw state, including pinned action versions and SHAs	Yes
.github/skills/	The exact Squad-owned gh-aw-enlistment skill; remove gh-aw's generated mutable agentic-workflows router before staging	Yes
.gitattributes	Marks compiled .lock.yml workflows as generated	Yes
.vscode/	Workspace settings that enable GitHub Copilot for Markdown files in VS Code	Optional — commit only if you want to share this workspace setting

agentics-maintenance.yml is a second installed workflow. Squad configures its created pull request safe output to expire after 14 days, so this workflow runs scheduled expiration cleanup and also exposes manual maintenance operations. To omit it, create .github/workflows/aw.json with {"maintenance": false} before installing. gh-aw then warns that expiration is disabled and removes the maintenance workflow.

Unlike the mutable router skill, agentics-maintenance.yml is compiled runtime output required for the configured 14-day safe-output expiration behavior. Keep it unless you explicitly disable maintenance before installation.

Retrospective auto-implementation (opt-in behavior)

squad-improvement-worker installs as part of the standard seven-workflow gh aw add command above — it is not a separate add-on. The two activation policies are separate: squad-retro can auto-dispatch squad-implement-worker on its own ordinary (non-proposal) action issues once you set "squadRetroAutoImplement": "allow" in .squad/config.json (only bot-authored retrospective issues with a valid Action-Key: qualify), and a maintainer can approve a governance-scoped retrospective proposal (paths under .squad/skills/** or .squad/decisions/inbox/** only) for automated implementation by commenting /squad approve-improvement, an Approved-Revision: content hash and one Approved-Path: line per approved file. The dispatcher forwards the issue and exact comment ID; the worker revalidates the human's permission, revision, revocations and actual patch. /squad revoke-improvement withdraws that authorization at any time — it is a reserved, read-only command open to any actor, and it emits no output of its own.

Report/proposal-only remains the default. Ordinary opt-in dispatch is capped at three per wake-up (five action issues per report), with one delayed retry and a durable human handoff after exhaustion. Both workers produce drafts only; open, merged and closed-unmerged linked PRs suppress automatic duplicates. Human review and merge are always required.

See the gh-aw guide for the full authority model.

Slash commands

Command	What it does
/squad	Cast a fresh team from repo analysis
/squad connect org/repo	Link to an external squad
/squad adopt org/repo	Fork a squad locally
/squad cast-member <spec>	Add a team member
/squad retire <name>	Remove a team member
/squad status	Check current team
/squad implement	Implement an issue or dispatch ready tasks from an epic
/squad retro	Run the shared retrospective now; scheduled and evidence-driven wakeups use the same worker
/squad approve-improvement	Authorize a governance-scoped retrospective proposal for squad-improvement-worker (write/maintain/admin only)
/squad revoke-improvement	Withdraw a prior approval; reserved, read-only, open to anyone

Casting brief tip

Write a detailed team description in the issue body, then comment /squad cast — the issue becomes your casting brief. The more context you give, the better Squad tailors your team.

📖 See GitHub Agentic Workflows guide for the complete setup, configuration, and usage reference.

---

Requirements

• Node.js ≥22.5.0
• npm ≥10.0.0
• Git with SSH agent
• GitHub CLI (gh) for GitHub integration

License

This project is licensed under the terms of the MIT open source license. Please refer to the LICENSE file for the full terms.

Maintainers

• @bradygaster
• @tamirdresher

See CODEOWNERS for the full list.

Support

For help or questions about using Squad, please use GitHub Discussions. See SUPPORT.md for details.

Contributing

We welcome contributions! See CONTRIBUTING.md for build setup, monorepo structure, and guidelines.

Code of Conduct

This project has adopted the Contributor Covenant Code of Conduct. See the full text for details on expected behavior and reporting.