How Squad runs coordinated AI agents inside your repository

Multi-agent coding without the orchestration tax

AI coding assistants usually follow the same loop: prompt, misinterpretation, refine, repeat. That works for small tasks, but once a project grows, the bottleneck shifts from writing prompts to coordinating design, implementation, testing, and review without losing context at every handoff.

Multi-agent systems are the usual answer, but they come with a heavy setup cost. Wiring orchestration layers, configuring frameworks, and standing up vector databases can consume hours before a single delegated task runs. Squad, an open-source project built on GitHub Copilot, takes a different approach: it initializes a preconfigured AI team directly inside a repository.

Getting started takes two commands—npm install -g @bradygaster/squad-cli once globally and squad init once per repo. That drops a specialized team—a lead, frontend developer, backend developer, and tester—into your project. There is no centralized infrastructure. Instead, Squad demonstrates what repository-native multi-agent orchestration looks like: a team whose context and history live in files committed alongside the code.

How work is routed and reviewed

You describe the task in natural language. A coordinator agent figures out the routing, loads repository context, and spawns specialists with task-specific instructions. For example, typing "Team, I need JWT auth—refresh tokens, bcrypt, the works." starts a parallel workflow: the backend specialist takes the implementation, the tester starts writing the test suite, and a documentation specialist opens a pull request. Files are written and branches are created within minutes.

What makes this different from a single chatbot switching roles is how the specialists stay aligned. They already know your naming conventions and past architectural decisions—not because you restated them in the prompt, but because agents load from shared team decisions and project history files committed to the repository.

Iteration is handled internally rather than through manual test-and-refine cycles. After the backend specialist drafts the implementation, the tester runs the suite against it. If tests fail, the code is rejected. Crucially, the orchestration layer prevents the originating agent from revising its own work. A different agent must step in and fix it. That forces genuine independent review with a separate context window and a fresh perspective, instead of asking a single AI to check its own mistakes. When reviewer automation is enabled, what you review is the pull request that survives that internal loop, not each intermediate attempt.

Squad is not autopilot. Agents ask clarifying questions and can make reasonable but wrong assumptions. You still review and merge every pull request. It's collaborative orchestration with human oversight, not fully autonomous execution.

Architectural patterns that make it work

Whether you use Squad or build your own multi-agent workflows, the architecture behind repository-native orchestration matters. These three patterns shift behavior from black-box to inspectable and predictable.

The "drop-box" pattern for shared memory

Real-time chat synchronization and vector database lookups are fragile ways to keep agents coordinated. Squad instead uses a "drop-box" pattern: every architectural choice—a library selection, a naming convention—is appended as a structured block to a versioned decisions.md file. This treats the markdown file as the team's shared brain, giving persistence, legibility, and a full audit trail. Because memory lives in project files rather than a live session, the team recovers context after disconnects or restarts and picks up where it left off.

Context replication over context splitting

Context window limits are a major obstacle in AI development. A single agent juggling meta-management with actual work crowds its working memory and invites hallucinations. Squad keeps the coordinator as a thin router: it spawns specialists rather than doing the work itself. Each specialist runs as a separate inference call with its own large context window (up to 200K tokens on supported models). Instead of splitting one context among four agents, you replicate the repository context across them. Running specialists in parallel gives you multiple independent reasoning contexts operating simultaneously, so each agent sees the relevant parts of the codebase without competing for space.

Explicit memory in the prompt vs. implicit memory in weights

An AI team's memory should be legible and versioned. Squad builds an agent's identity on two plain-text repository files: a charter (who they are) and a history (what they've done), alongside shared team decisions. Because these live in the .squad/ folder, the AI's memory is versioned alongside your code. Cloning the repo gives you more than source—it gives you an already onboarded AI team whose memory ships with the project.

A low-ceremony entry point

The main win of Squad is accessibility. It removes the infrastructure overhead, complex prompt engineering, and convoluted CLI interactions that usually gate agentic development. For a closer look at repository-native orchestration, the Squad repository is the place to start. Throw a squad at a problem to see how the workflow evolves.