How Squad runs coordinated AI agents inside your repository

Source: GitHub Blog

Squad: Repository‑Native Multi‑Agent Orchestration

If you’ve used AI coding tools before, you know the pattern:

1. Write a prompt.
2. The model misunderstands.
3. Refine the prompt.
4. Coax a better output.

Progress depends more on steering the model than on building the software.

---

The scaling problem

As projects grow, the challenge shifts from “how do I prompt?” to “how do I coordinate design, implementation, testing, and review without losing context?”

Multi‑agent systems can break through this plateau, but they usually demand:

• Hours of orchestration‑layer setup.
• Complex wiring of frameworks.
• Configuration of vector databases.

All of this just to delegate a single task.

---

Introducing Squad

Squad is an open‑source project built on GitHub Copilot that initializes a pre‑configured AI team directly inside your repository. It shows that multi‑agent development can be:

• Accessible
• Legible
• Useful

…without heavy orchestration infrastructure or deep prompt‑engineering expertise.

What you get

Running Squad creates a specialized AI team consisting of:

• Lead – guides the overall direction.
• Frontend developer – writes UI code.
• Backend developer – handles server‑side logic.
• Tester – generates and runs tests.

All agents operate natively on your repository, eliminating the need for a separate centralized orchestration layer.

---

Quick start

# Install the CLI globally (once)
npm install -g @bradygaster/squad-cli

# Initialise Squad in a repository (once per repo)
squad init

After these two commands, Squad drops the AI team into your project, ready to collaborate on design, implementation, testing, and review.

---

In short: Instead of a single chatbot that switches roles, Squad demonstrates repository‑native multi‑agent orchestration without heavy centralized infrastructure.

How Squad Coordinates Work Across Agents

You describe the work you need done in natural language. From there, a coordinator agent inside Squad:

1. Figures out the routing.
2. Loads repository context.
3. Spawns specialists with task‑specific instructions.

Example workflow

You type:

Team, I need JWT auth—refresh tokens, bcrypt, the works.

Then you watch the team spin up in parallel:

Within minutes, files are written and branches are created. These specialists already know your naming conventions and the database‑connection decisions you made last Tuesday—not because you put them in the prompt, but because agents load from shared team decisions and their own project‑history files committed to the repository.

Iteration & Review

Instead of forcing you to manually test the output and prompt the model through multiple rounds of fixes, Squad handles iteration internally:

1. The backend specialist drafts the initial implementation.
2. The tester runs the test suite against it.
3. If the tests fail, the tester rejects the code.

The orchestration layer prevents the original agent from revising its own work. Squad’s reviewer protocol can block the original author from fixing rejected code; a different agent must step in. This enforces genuine independent review with a fresh context window and perspective, rather than having a single AI review its own mistakes.

When reviewer automation is enabled, you only review the pull request that survives this internal loop, not every intermediate attempt.

Key Takeaways

• Collaborative orchestration, not autonomous execution.
• Agents may ask clarifying questions and sometimes make reasonable but wrong assumptions.
• You still review and merge every pull request.
• The system promotes independent review and reduces repetitive manual testing.

Architectural Patterns Behind Repository‑Native Orchestration

Whether you use Squad or build your own multi‑agent workflows, we’ve identified a few architectural patterns that move orchestration away from “black‑box” behavior toward something inspectable and predictable at the repository level.

---

1. The “Drop‑Box” Pattern for Shared Memory

Most AI orchestration relies on real‑time chat or complex vector‑database lookups to keep agents in sync. In practice, this approach is fragile—synchronizing state across live agents quickly becomes a fool’s errand.

Squad’s solution: treat a markdown file as the team’s shared brain.

• Every architectural choice (e.g., library selection, naming convention) is appended as a structured block to a versioned‑decisions.md file in the repository.
• The file lives in the repo, so it benefits from persistence, legibility, and an immutable audit trail of every decision.
• Because the memory is stored in project files rather than a live session, the team can recover context after disconnects or restarts and continue exactly where it left off.

---

2. Context Replication > Context Splitting

The context‑window limit is one of the biggest hurdles in AI development. When a single agent tries to do everything, its “working memory” fills with meta‑management, leading to hallucinations.

Squad’s approach: keep the coordinator agent thin and let it spawn specialists.

• Each specialist runs as an independent inference call with its own large context window (e.g., up to 200 K tokens on supported models).
• Instead of splitting one context among several agents, we replicate the repository context for each specialist.
• Running multiple specialists in parallel yields independent reasoning contexts that can each “see” the relevant parts of the repository without competing for space.

---

3. Explicit Memory in the Prompt vs. Implicit Memory in the Weights

An AI team’s memory should be legible and versioned. You shouldn’t have to guess what an agent “knows” about your project.

In Squad, an agent’s identity is built primarily on two repository files:

Both files live in the .squad/ folder alongside shared team decisions. Because they are plain text and version‑controlled, the AI’s memory travels with the code. When you clone a repository, you receive not only the source code but also an already onboarded AI team, with its memory stored directly in the repo.

---

By adopting these patterns—drop‑box shared memory, context replication, and explicit, versioned prompts—you can build AI‑driven workflows that are transparent, resilient, and tightly coupled to the code they help manage.

Lowering the barrier to multi‑agent workflows

Our biggest win with Squad is that it makes it easy for anyone to get started with agentic development in a low‑touch, low‑ceremony way. You shouldn’t have to spend hours wrestling with infrastructure, learning complex prompt engineering, or managing convoluted CLI interactions just to get an AI team to help you write code.

To see what repository‑native orchestration feels like, check out the Squad repository and throw a squad at a problem to see how the workflow evolves.

---

Author

Brady Gaster – Principal PM Architect in CoreAI Apps & Agents at Microsoft, where he builds tools that make it easier for people to party with Copilot in the cloud.

---

Related posts

• [Docs](https://github.com) – Everything you need to master GitHub, all in one place.
• [GitHub](https://github.com) – Build what’s next on GitHub, the place for anyone from anywhere to build anything.
• [Customer stories](https://github.com) – Meet the companies and engineering teams that build with GitHub.
• [The GitHub Podcast](https://github.com) – Catch up on the GitHub podcast, a show dedicated to topics, trends, stories, and culture in and around the open‑source developer community on GitHub.

(Icons have been omitted for brevity; you can re‑add them with standard markdown image syntax if desired.)