Human-led AI agent teams for any project. One command. A team that helps you move faster with your code.
⚠️ Alpha Software — Squad is experimental. APIs and CLI commands may change between releases. We'll document breaking changes in CHANGELOG.md.
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.
mkdir my-project &&cd my-project
git init✓ Validate: Run git status — you should see "No commits yet".
npm install -g @bradygaster/squad-cli
squad init✓ Validate: Check that .squad/team.md was created in your project.
gh auth login✓ Validate: Run gh auth status — you should see "Logged in to github.com".
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.
Upgrading Squad is a two-step process.
Step 1: Update the CLI binary
npm install -g @bradygaster/squad-cli@latestStep 2: Update Squad-owned files in your project
squad upgradesquad upgrade updates squad.agent.md, templates, and GitHub workflows to the latest versions. 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.
| Command | What it does |
|---|---|
squad init | Init — scaffold Squad in the current directory (idempotent — safe to run multiple times); alias: hire; use --global to init in personal squad directory, --mode remote <path> for dual-root mode |
squad upgrade | Update Squad-owned files to latest; never touches your team state; use --global to upgrade personal squad, --migrate-directory to rename .ai-team/ → .squad/ |
squad upgrade --self | Update the Squad CLI package itself; add --insider for prerelease builds |
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/) |
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.
# Monitor for issues (triage mode — no execution)
npx @bradygaster/squad-cli watch
# Monitor and auto-execute against actionable issues
npx @bradygaster/squad-cli watch --execute --interval 5
# With custom agent runner and copilot flags
npx @bradygaster/squad-cli watch --execute \
--agent-cmd "agency copilot" \
--copilot-flags "--yolo --autopilot --mcp mail --agent squad" \
--auth-user myaccount
# Run watch with diagnostics
npx @bradygaster/squad-cli watch --execute --log-file ./watch.log --verbose
# Check health of running watch process
npx @bradygaster/squad-cli watch --health| 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 (default: gh copilot) |
--copilot-flags | Flags passed to the agent 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) |
Ralph uses an agent-delegated selection pattern:
- Ralph scans for triage-eligible issues (unassigned, labeled, etc.)
- Ralph builds a context snapshot: issue list, squad state, recent decisions
- Ralph writes this context to a temp file using the
-p <path>flag - Ralph invokes the agent with that file:
gh copilot -p context.md - The agent decides which issue to work on and how
- 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.
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.
Watch includes a tiered remediation strategy:
- Tier 1 — Circuit Breaker Reset: Clear and retry
- Tier 2 — Auth Reprobe: Re-verify credentials
- Tier 3 — Git Pull: Update local state
- Tier 4 — Pause 30m: Back off for human intervention
This prevents watch from spamming the same failure endlessly.
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-branchTo 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 dirsWatch automatically prunes stale artifacts:
- Scratch directories older than 7 days
- Log files older than 30 days
- Orphaned orchestration state
Check on a running watch:
squad watch --healthOutput example:
Ralph Watch Status
PID: 12345
Uptime: 2h 15m
Last Poll: 2 minutes ago
Auth: Ready (account: myaccount@github.com)
Capabilities: Issue triage, PR review, ADO sync
Next Poll: 14:35 (in 3 minutes)
Round: 42 / 1200
⚠️ Deprecated: The interactive shell (squadwith no arguments) has been deprecated. For the best Squad experience, use the GitHub Copilot CLI instead.copilot --agent squadSee Choose your interface for current options.
Tired of typing squad followed by a command every time? Enter the interactive shell.
squadNo arguments. Just squad. You'll get a prompt:
squad >
You're now connected to your team. Talk to them.
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) |
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.
- 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.mdfor the whole team to see
For more details on shell usage, see the commands table above.
Eight working examples from beginner to advanced — casting, governance, streaming, Docker. See samples/README.md.
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 madeorchestration-log/— what was spawned, why, and what happenedlog/— 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.
.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.
⚠️ 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.tsimport{defineSquad,defineTeam,defineAgent}from'@bradygaster/squad-sdk';exportdefaultdefineSquad({team: defineTeam({name: 'Platform Squad',members: ['@edie','@mcmanus']}),agents: [defineAgent({name: 'edie',role: 'TypeScript Engineer',model: 'claude-sonnet-4'}),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.
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
# 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# Run all tests
npm test# Watch mode
npm run test:watch# Type check (no emit)
npm run lintSquad uses changesets for independent versioning across packages:
# Add a changeset
npx changeset add
# Validate changesets
npm run changeset:checkChangesets are resolved on the main branch; releases happen independently per package.
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