bradygaster / squad

Squad **AI agent teams for any project.** One command. A team that grows with your code. > ⚠️ **Alpha Software** — Squad is experimental. APIs and CLI commands may change between releases. We'll document breaking changes in CHANGELOG.md. --- What is Squad? Squad gives you an 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 get better the more you use them. 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. --- Quick Start • Create your project **✓ Validate:** Run — you should see "No commits yet". • Install Squad **✓ Validate:** Check that was created in your project. **Or use npx (no install):** — see Migration Guide if upgrading from an older version. • Authenticate with GitHub (for Issues, PRs, and Ralph) **✓ Validate:** Run — you should see "Logged in to github.com". • Open Copilot and go > **Why ?** 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: **✓ Validate:** Squad responds with team member proposals. Type 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. --- All Commands (15 commands) | Command | What it does | |---------|-------------| | | **Init** — scaffold Squad in the current directory (idempotent — safe to run multiple times); alias: ; use to init in personal squad directory, for dual-root mode | | | Update Squad-owned files to latest; never touches your team state; use to upgrade personal squad, to rename → | | | Show which squad is active and why | | | Watch issues and auto-triage to team (aliases: , ); use to set polling frequency (default: 10) | | | Add/remove the Copilot coding agent (@copilot); use to remove, to enable auto-assignment | | | Check your setup and diagnose issues (alias: ) | | | Connect to a remote team | | | Launch interactive shell explicitly | | | Export squad to a portable JSON snapshot | | | Import squad from an export file | | | Manage plugin marketplaces | | | Manage upstream Squad sources | | | Context hygiene — compress, prune, archive; use for aggressive compression, to preview changes | | | Open Aspire dashboard for observability | | | Remove email addresses from Squad state files (default: ) | --- Interactive Shell Tired of typing followed by a command every time? Enter the interactive shell. Entering the Shell No arguments. Just . You'll get a prompt: You're now connected to your team. Talk to them. Shell Commands All shell commands start with : | Command | What it does | |---------|-------------| | | Check your team and what's happening | | | See recent messages | | | List all team members | | | List saved sessions | | | Restore a past session | | | Show version | | | Clear the screen | | | Show all commands | | | Exit the shell (or Ctrl+C) | Talking to Agents Use (case-insensitive) or natural language with a comma: 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 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. --- Insider Channel Want the latest features before they ship? For insider builds: > **Note:** GitHub-native distribution ( ) has been removed. All distribution is now via npm (see Migration Guide for details). --- Agents Work in Parallel — You Catch Up When You're Ready Squad doesn't work on a human schedule. When you give a task, the coordinator launches every agent that can usefully start — simultaneously. When agents finish, the coordinator immediately chains follow-up work. If you step away, a breadcrumb trail is waiting when you get back: • ** ** — every decision any agent made • ** ** — what was spawned, why, and what happened • ** ** — full session history, searchable **Knowledge compounds across sessions.** Every time an agent works, it writes lasting learnings to its . 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. --- What Gets Created **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) Prefer TypeScript? You can define your team in code instead of markdown. Create a with builder functions, run , and the files are generated automatically. Run to generate all the markdown. See the SDK-First Mode Guide for full documentation. --- Monorepo Development Squad is a monorepo with two packages: • ** ** — Core runtime and library for programmable agent orchestration • ** ** — Command-line interface that depends on the SDK Building Testing Linting Publishing Squad uses changesets for independent versioning across packages: Changesets are resolved on the branch; releases happen independently per package. --- The SDK: Programmable Agent Runtime > Everything above works out of the box. The sections below are for deve…