# bradygaster/squad: AI agent teams that live as files in your repo > Squad scaffolds a human-led team of Copilot agents (frontend, backend, tester, lead) into a .squad directory, and each member keeps its own context. It is alpha software with a real CLI, a .NET preview package, and a container image, but the docs are thinner than the command table suggests. **bradygaster/squad** — Squad: AI agent teams for any project. For the best Squad experience, use the [GitHub Copilot CLI]. - Repository: https://github.com/bradygaster/squad - Website: https://bradygaster.github.io/squad/ - Stars: 3,234 · Forks: 497 - Language: TypeScript - License: MIT - Published: 2026-08-08 · Updated: 2026-08-18 · Language: en - Canonical page: https://hysenlabs.com/projects/bradygaster-squad ## The problem Squad targets, and who it is actually for Most agent tooling asks you to describe a task and hope the single assistant remembers enough. Squad takes a different position: the team is the unit. The README describes it as "Human-led AI agent teams for any project", and the operating claim is that each team member "runs in its own context, reads only its own knowledge, and writes back what it learned so the work stays inspectable". The target user is a developer already inside GitHub Copilot who wants parallel work without handing over judgement. The README is explicit that Squad is "a productivity tool for humans, not a replacement for engineers, reviewers, or decision-makers", and that people stay accountable for priorities, approvals, and final changes. If your workflow has no human reviewer at the end, Squad's design assumptions do not match your situation. There is a second, narrower audience: .NET teams. The repository ships Squad.Agents.AI under src/Squad.Agents.AI as a preview NuGet package that registers a Squad-backed AIAgent in dependency injection. That package targets early 0.1.0-preview consumers, which tells you how much production weight it is meant to carry right now. ## How the team persists: files, charters and per-member context The mechanism is deliberately unglamorous. Squad writes state into a .squad directory in your project. The quick start validation step is checking that .squad/team.md exists, and the upgrade documentation says squad upgrade "never touches your .squad/ team state", listing agents, decisions and history as the things preserved. So the team is a directory of files, not a service. The README contrasts this with "a chatbot wearing hats". Each member has a name drawn from what the README calls "a persistent thematic cast", and the repository ships meet-the-squad.md at the top level alongside a .squad-templates directory, which is where the scaffolding comes from. During setup, Squad proposes members and you confirm with yes. State does not have to stay in the working tree. squad externalize moves .squad/ outside it, and the README says the reason is that externalized state "survives branch switches". squad internalize moves it back. That pair is the clearest signal of intent: the team is treated as durable infrastructure attached to a project, not as a byproduct of one branch. There is also a container path. The Dockerfile documents a contract with WORKDIR /app, non-root uid 1001, SIGTERM drain, and squad watch --execute as the default command. It builds from a standalone bundle produced by scripts/build-standalone.mjs rather than installing the CLI from the registry at image build time, so the final image has no runtime dependency on registry.npmjs.org. ## Installing Squad and running a first session The README's quick start assumes you have Node and npm already. Create an empty repository first, because Squad scaffolds into the current directory. ```bash mkdir my-project && cd my-project git init ``` The README's validation step is to run git status and confirm you see "No commits yet". Then install the CLI globally and initialise. ```bash npm install -g @bradygaster/squad-cli squad init ``` The README notes that squad init is idempotent and safe to run more than once. If you want a pre-built team instead of the step-by-step walkthrough, the documented shortcut is squad init --preset default, which the README says produces members, charters and routing rules ready to go. The validation step is to confirm .squad/team.md was created. GitHub authentication is a separate step and only matters if you want Issues, PRs and the Ralph workflow. ```bash gh auth login ``` The README asks you to confirm with gh auth status showing "Logged in to github.com". Then launch Copilot with the Squad agent. ```bash copilot --agent squad --yolo ``` The README explains the --yolo flag plainly: Squad makes many tool calls in a typical session, and without it Copilot prompts for approval on each one. In VS Code the equivalent is opening Copilot Chat and selecting the Squad agent. The first prompt the README suggests is telling Squad what you are building and asking it to set up the team; Squad responds with member proposals and you type yes to confirm. ## Upgrades are split in two, and that split is the interesting part Squad does not treat the CLI and your project files as one artefact. Upgrading is documented as two steps. First the binary: ```bash npm install -g @bradygaster/squad-cli@latest ``` Then the project-owned files: ```bash squad upgrade ``` The README states that squad upgrade updates squad.agent.md, templates and GitHub workflows, and that it never touches .squad/ team state. A --force flag re-applies updates even when the installed version already matches. There is also squad upgrade --self for the CLI package itself, with --insider for dev-channel prerelease builds, and a --migrate-directory flag that renames .ai-team/ to .squad/, which confirms an older directory name existed. This separation is the project's best design decision on paper. It means a broken upgrade cannot erase the decisions and history your agents accumulated. The cost is that you now have two version numbers to reason about, and nothing in the README describes how to roll back if squad upgrade writes a template you do not want. The README does not document rollback. If reversibility matters to you, commit .squad/ and the generated workflow files separately so the two can be reverted independently. ## Where Squad is the wrong tool The README carries its own warning: Squad is "experimental", APIs and CLI commands may change between releases, and breaking changes are documented in CHANGELOG.md. The command table lists 17 commands, one of which (squad shell) is already deprecated in favour of copilot --agent squad. That is a young surface area. A second limitation is the watch loop. squad triage polls for issues and auto-triages them to the team, with a default interval of 10 minutes, and only dispatches Copilot agents when you add --execute. A polling loop that can spawn agents is not something to point at a repository where issue creation is open to the public without thinking about what it will pick up. The README gives --log-file for diagnostics and --health for watch status, which suggests the authors expect it to run unattended, but it does not describe rate limiting or a maximum number of dispatched agents. Third, the whole thing assumes GitHub Copilot. The README's own framing is that Squad amplifies "a human operator with GitHub Copilot". If your organisation has not adopted Copilot, or runs agents against a different provider, the team files are inert. The .NET package does not change that; it registers a Squad-backed agent inside the Microsoft Agent Framework, it does not replace the underlying Copilot dependency. Finally, the engine field in package.json requires Node >=22.5.0. Older Node installations will fail before any of this runs. ## How this differs from a general-purpose agent framework Microsoft's Agent Framework is the obvious comparison point, and the repository itself points at it: Squad.Agents.AI registers a Squad-backed AIAgent in DI for consumers of that framework. The difference in approach is where the team definition lives. A general agent framework gives you primitives (agents, tools, orchestration) and expects you to assemble and host them. Squad ships the assembly as files committed to your repository, with an opinionated cast of roles and a CLI to scaffold, upgrade and inspect them. That makes Squad narrower and more prescriptive, and it makes the two complementary rather than competing. If you want to build an agent product, the framework is the substrate. If you want a frontend, backend, tester and lead working on the repository you are already in, and you want to see their state with git diff, Squad is the layer that gives you that. The same distinction applies against the Copilot coding agent. squad copilot adds or removes the @copilot coding agent and can enable auto-assignment with --auto-assign. That is a single agent attached to issues. Squad's claim is a set of members with separate contexts and shared decisions, which is a different shape of coordination, not a better version of the same thing. ## Licence, maintenance and what it costs to keep current Squad is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is the whole of the licence implication here; nothing in the repository suggests a dual licence, a contributor licence agreement that changes distribution terms, or a separate commercial tier. If your legal team has questions about the preview NuGet package or the container image, those are questions for them, not for this article. On maintenance, the last push to the repository was on 2026-08-26, and v0.13.1 was released the same day, following v0.13.0 the day before and v0.12.0 on 2026-08-13. The repository is not archived. The cadence visible in the release list is frequent, and the CHANGELOG.md file at the top level is the place the README says breaking changes will be recorded. The upgrade cost is low by design: two commands, with squad upgrade deliberately excluded from your team state. The hidden cost is drift between the CLI version and the project files, which is exactly what squad update-check exists to report. It reads a cached status, supports --json for tooling and CI, and --refresh bypasses the cache. Wiring that into CI is the one piece of ongoing work the project hands you. ## Conclusion Adopt Squad if you already work inside GitHub Copilot and want agent roles that persist in the repository rather than in a chat window; the MIT licence and the fact that squad upgrade never touches .squad/ keep the exit cheap. Do not adopt it if you need stable CLI flags, because the README marks the project alpha and reserves the right to change commands between releases. Before committing, run squad doctor on a scratch repo, confirm .squad/team.md is created, and check that your Node version satisfies the >=22.5.0 engine field in package.json. ## FAQ ### What is the Squad team in bradygaster/squad? It is a set of AI team members (the README names frontend, backend, tester and lead as examples) that live in your repository as files under .squad. You describe what you are building, Squad proposes members, and you confirm with yes. ### How do I install Squad? Install the CLI globally with npm install -g @bradygaster/squad-cli, then run squad init inside your project. The README's validation step is to confirm that .squad/team.md was created. ### Does squad upgrade delete my team's agents and decisions? No. The README states that squad upgrade updates squad.agent.md, templates and GitHub workflows, and never touches .squad/ team state, so agents, decisions and history are preserved. ### What Node version does bradygaster/squad require? The engines field in the repository's package.json declares node >=22.5.0. Anything older will not satisfy the declared engine requirement. ### Is bradygaster/squad stable enough for production use? The README labels Squad alpha software and experimental, and warns that APIs and CLI commands may change between releases, with breaking changes recorded in CHANGELOG.md. Squad shell is already marked deprecated in favour of copilot --agent squad. ## Sources - [Official documentation](https://bradygaster.github.io/squad/) - [Official README](https://github.com/bradygaster/squad#readme) - [Project repository](https://github.com/bradygaster/squad) - [Release notes](https://github.com/bradygaster/squad/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/bradygaster-squad