squad

squad

Squad: AI agent teams for any project

Stars: 103

Visit
 screenshot

Squad is an AI development tool that provides a team of specialists (frontend, backend, tester, lead) through GitHub Copilot. Each team member runs in its own context, learns your codebase, shares decisions, and improves over time. The tool works by launching agents in parallel to work on tasks simultaneously, with knowledge compounding across sessions. Squad stores team-wide decisions in `decisions.md` and individual agent learnings in `history.md`. The tool operates within a 200K token context window per agent, with optimizations to maximize actual work capacity. Squad's memory architecture includes `charter.md`, `history.md`, `decisions.md`, and `log/` for session history. The tool creates a `.ai-team/` folder with team roster, routing, decisions, and agent information, ensuring persistence and knowledge sharing. Squad allows for adding and removing team members, review protocols, and issue assignment and triage integration with GitHub Issues. It offers various features like client compatibility, VS Code support, project boards integration, label taxonomy, notifications, MCP setup guide, plugin marketplace, universe expansion, and more.

README:

Squad

AI agent teams for any project. A team that grows with your code.

Status Platform

πŸ“£ Join the Squad Community β€” meet contributors, see deployments, share your work.


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

1. Create your project

mkdir my-project && cd my-project
git init

2. Install Squad

npx github:bradygaster/squad

3. Authenticate with GitHub (for Issues, PRs, and Ralph)

gh auth login

If you plan to use Project Boards, add the project scope:

gh auth refresh -s project

4. Open Copilot and go

copilot

Select Squad (vX.Y.Z) from the /agents list, 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.

Squad proposes a team β€” each member named from a persistent thematic cast. You say yes. They're ready.


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. Frontend, backend, tests, architecture β€” all at once.

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 immediately chains follow-up work β€” tests reveal edge cases, the backend agent picks them up, no waiting for you to ask. If you step away, a breadcrumb trail is waiting when you get back:

  • decisions.md β€” every decision any agent made, merged by Scribe
  • orchestration-log/ β€” what was spawned, why, and what happened
  • log/ β€” 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.

🌱 First session 🌿 After a few sessions 🌳 Mature project
βš›οΈ Frontend Project structure, framework choice Component library, routing, state patterns Design system, perf patterns, a11y conventions
πŸ”§ Backend Stack, database, initial endpoints Auth strategy, rate limiting, SQL preferences Caching layers, migration patterns, monitoring
πŸ—οΈ Lead Scope, team roster, first decisions Architecture trade-offs, risk register Full project history, tech debt map
πŸ§ͺ Tester Test framework, first test cases Integration patterns, edge case catalog Regression patterns, coverage gaps, CI pipeline
πŸ“‹ Scribe First session logged Cross-team decisions propagated Full searchable archive of every session and decision
πŸ”„ Ralph Board check after first batch Auto-triage, CI monitoring Continuous backlog processing, zero idle time

Each agent's knowledge is personal β€” stored in its own history.md. Team-wide decisions live in decisions.md, where every agent reads before working. The more you use Squad, the less context you have to repeat.

And it's all in git. Anyone who clones your repo gets the team β€” with all their accumulated knowledge.


How It Works

The Key Insight

Each agent gets its own context window. The coordinator is thin. Each agent loads only its charter + history. No shared bloat.

graph TB
    U["πŸ§‘β€πŸ’» You"] -->|"Team, build the login page"| C["GitHub Copilot"]

    subgraph team [" 🏒 The Team "]
        direction LR
        A["πŸ—οΈ Lead"]
        K["βš›οΈ Frontend"]
        R["πŸ”§ Backend"]
        T["πŸ§ͺ Tester"]
    end

    C -->|spawns| A
    C -->|spawns| K
    C -->|spawns| R
    C -->|spawns| T
    C -.->|silent| S["πŸ“‹ Scribe"]
    C -.->|monitors| RL["πŸ”„ Ralph"]

    subgraph memory [" 🧠 Shared Memory "]
        direction LR
        D["decisions.md"]
        L["log/"]
    end

    A & K & R & T -->|read & write| D
    S -->|merges & logs| D
    S -->|writes| L

    A -->|learns| HA["history.md"]
    K -->|learns| HK["history.md"]
    R -->|learns| HR["history.md"]
    T -->|learns| HT["history.md"]

    style U fill:#000,color:#fff,stroke:#333
    style C fill:#000,color:#fff,stroke:#333
    style A fill:#000,color:#fff,stroke:#333
    style K fill:#000,color:#fff,stroke:#333
    style R fill:#000,color:#fff,stroke:#333
    style T fill:#000,color:#fff,stroke:#333
    style S fill:#000,color:#fff,stroke:#333
    style D fill:#000,color:#fff,stroke:#333
    style L fill:#000,color:#fff,stroke:#333
    style HA fill:#000,color:#fff,stroke:#333
    style HK fill:#000,color:#fff,stroke:#333
    style HR fill:#000,color:#fff,stroke:#333
    style HT fill:#000,color:#fff,stroke:#333
    style team fill:none,stroke:#fff,stroke-width:2px,stroke-dasharray:5 5
    style memory fill:none,stroke:#fff,stroke-width:2px,stroke-dasharray:5 5

Context Window Budget

Real numbers. No hand-waving. Updated as the project grows.

Both Claude Sonnet 4 and Claude Opus 4 have a 200K token standard context window. Each agent runs in its own window, so the coordinator is the only shared overhead.

What Tokens % of 200K context When
Coordinator (squad.agent.md) ~26,300 13.2% Every message
Agent spawn overhead (charter ~750 + inlined in prompt) ~750 0.4% When spawned
decisions.md (shared brain β€” read by every agent) ~32,600 16.3% When spawned
Agent history (varies: 1K fresh β†’ 12K veteran) ~1,000–12,000 0.5–6.0% When spawned
Total agent load (charter + decisions + history) ~34,000–45,000 17–23% When spawned
Remaining for actual work ~155,000–166,000 78–83% Always

v0.4.0 context optimization (Feb 2026): We ran a context budget audit and found decisions.md had ballooned to ~80K tokens (40% of context) after 250+ accumulated decision blocks. Combined with spawn template duplication in the coordinator, agents were working with barely half a context window. Three targeted optimizations shipped:

  1. decisions.md pruning β€” 251 blocks β†’ 78 active decisions. Stale sprint artifacts, completed analysis docs, and one-time planning fragments archived to decisions-archive.md. Nothing deleted β€” full history preserved.
  2. Spawn template deduplication β€” Three near-identical templates (background, sync, generic) collapsed to one. Saved ~3,600 tokens in the coordinator prompt.
  3. Init Mode compression β€” 84 lines of first-run-only instructions compressed to 48 lines. Same behavior, less prose.

Result: Per-agent spawn cost dropped from 41–46% to 17–23% of context. Agents now have ~78–83% of their context window for actual work, up from ~54–59%. As your squad runs more sessions and accumulates more decisions, Scribe's history summarization keeps per-agent history bounded. For decisions.md, a Scribe-driven automated pruning system is planned for v0.5.0 (see issue #37) β€” until then, the archive pattern keeps the shared brain lean.

The architecture still wins. Each agent runs in its own 200K window. The coordinator's window is separate from every agent's window. Fan out to 5 agents and you're working with ~1M tokens of total reasoning capacity. The per-agent overhead is real but bounded β€” and the pruning system ensures it stays that way as your project grows.

Memory Architecture

Layer What Who writes Who reads
charter.md Identity, expertise, voice Squad (at init) The agent itself
history.md Project-specific learnings Each agent, after every session That agent only
decisions.md Team-wide decisions Any agent All agents
log/ Session history Scribe Anyone (searchable archive)

What Gets Created

.ai-team/
β”œβ”€β”€ team.md              # Roster β€” who's on the team
β”œβ”€β”€ routing.md           # Routing β€” who handles what
β”œβ”€β”€ decisions.md         # Shared brain β€” team decisions
β”œβ”€β”€ casting/
β”‚   β”œβ”€β”€ policy.json      # Casting configuration
β”‚   β”œβ”€β”€ registry.json    # Persistent name registry
β”‚   └── history.json     # Universe usage history
β”œβ”€β”€ agents/
β”‚   β”œβ”€β”€ {name}/          # Each agent gets a persistent cast name
β”‚   β”‚   β”œβ”€β”€ charter.md   # Identity, expertise, voice
β”‚   β”‚   └── history.md   # What they know about YOUR project
β”‚   β”œβ”€β”€ {name}/
β”‚   β”‚   β”œβ”€β”€ charter.md
β”‚   β”‚   └── history.md
β”‚   └── scribe/
β”‚       └── charter.md   # Silent memory manager
└── log/                 # Session history

Commit this folder. Your team persists. Names persist. Anyone who clones gets the team β€” with the same cast.


Growing the Team

Adding Members

> I need a DevOps person.

Squad generates a new agent, seeds them with project context and existing decisions. Immediately productive.

Removing Members

> Remove the designer β€” we're past that phase.

Agents aren't deleted. Their charter and history move to .ai-team/agents/_alumni/. Knowledge preserved, nothing lost. If you need them back later, they remember everything.


Reviewer Protocol

Team members with review authority (Tester, Lead) can reject work. On rejection, the reviewer may require:

  • A different agent handles the revision (not the original author)
  • A new specialist is spawned for the task

The Coordinator enforces this. No self-review of rejected work.


What's New in v0.4.0

  • Client Compatibility β€” Full platform support matrix. Squad now works on CLI and VS Code with graceful degradation.
  • VS Code Support β€” First-class VS Code guide. runSubagent parallel spawning, platform detection, feature degradation table.
  • Project Boards β€” GitHub Projects V2 integration. Board + Kanban views synced from labels. gh auth refresh -s project required.
  • Label Taxonomy β€” 7-namespace label system (status:, type:, priority:, squad:, go:, release:, era:). Labels are the state machine; boards are projections.
  • Notifications β€” Your squad pings you on Teams, iMessage, or Discord when they need input. Zero infrastructure in Squad β€” bring your own MCP notification server.
  • MCP Setup Guide β€” Step-by-step MCP configuration for CLI and VS Code. Examples: GitHub, Trello, Aspire dashboard.
  • Plugin Marketplace β€” Discover and install curated agent templates and skills from community repositories. Auto-recommend plugins when adding team members.
  • Universe Expansion β€” 20 β†’ 33 casting universes (MCU, DC, Stranger Things, The Expanse, Arcane, Ted Lasso, Dune, Cowboy Bebop, Fullmetal Alchemist, Seinfeld, The Office, Adventure Time, Futurama, + 2 more)
  • Docs Growth β€” 49 docs across features, scenarios, and guides
  • Context Optimization β€” decisions.md pruned from ~80K to ~33K tokens (251 β†’ 78 blocks). Spawn templates deduplicated. Per-agent context usage dropped from 41–46% to 17–23%. Agents now have 78–83% of their context window for actual work.
  • Core Growth β€” squad.agent.md: 1,100 β†’ 1,771 lines; index.js: 654 lines; 188+ total commits

What's New in v0.3.0

  • Per-Agent Model Selection β€” Cost-first routing: code work gets standard-tier models (claude-sonnet-4.5), non-code tasks use fast/cheap models (claude-haiku-4.5). 16-model catalog with fallback chains.
  • Ralph β€” Work Monitor β€” Built-in squad member that autonomously processes backlogs. Self-chaining work loop: scan GitHub β†’ spawn agents β†’ collect results β†’ repeat.
  • @copilot Coding Agent β€” GitHub's Copilot agent as a squad member. Three-tier capability profile. Auto-assign with workflow.
  • Universe Expansion β€” 14 β†’ 20 casting universes (Succession, Severance, Lord of the Rings, Attack on Titan, Doctor Who, Monty Python)
  • Milestones Rename β€” "Sprints" β†’ "Milestones" (GitHub-native alignment)
  • Test Growth β€” 92 β†’ 118 tests
  • Emoji Fixes β€” Test suite encoding standardized

What's New in v0.2.0


Issue Assignment & Triage

Squad integrates with GitHub Issues. Label an issue with squad to trigger triage, or assign directly to a member with squad:{name}.

How It Works

  1. Label an issue squad β€” the Lead auto-triages it: reads the issue, determines who should handle it, applies the right squad:{member} label, and comments with triage notes.

  2. squad:{member} label applied β€” the assigned member picks up the issue in their next Copilot session (or automatically if Copilot coding agent is enabled).

  3. Reassign β€” remove the current squad:* label and add a different member's label.

Labels

Labels are auto-created from your team roster via the sync-squad-labels workflow:

Label Purpose
squad Triage inbox β€” Lead reviews and assigns
squad:{name} Assigned to a specific squad member
squad:copilot Assigned to @copilot for autonomous coding agent work

Labels sync automatically when .ai-team/team.md changes, or you can trigger the workflow manually.

Workflows

Squad installs three GitHub Actions workflows:

Workflow Trigger What it does
sync-squad-labels.yml Push to .ai-team/team.md, manual Creates/updates squad:* labels from roster
squad-triage.yml squad label added to issue Lead triages and assigns squad:{member} label
squad-issue-assign.yml squad:{member} label added Acknowledges assignment, queues for member

Prerequisites

  • GitHub Actions must be enabled on the repository
  • The GITHUB_TOKEN needs issues: write and contents: read permissions
  • For @copilot auto-assign: a classic PAT with repo scope stored as COPILOT_ASSIGN_TOKEN repo secret (see setup guide)
  • For automated issue work: Copilot coding agent must be enabled on the repo

Session Awareness

The coordinator checks for open squad:{member} issues at session start and will mention them: "Hey {user}, {AgentName} has an open issue β€” #42: Fix auth endpoint timeout. Want them to pick it up?"


Install

npx github:bradygaster/squad

Appears to hang? npm resolves github: packages via git+ssh://. If no SSH agent is running, git prompts for your key passphrase β€” but npm's progress spinner hides the prompt. Fix: start your SSH agent first (ssh-add), or run with npx --progress=false github:bradygaster/squad to reveal the prompt. See Troubleshooting for more.

See Quick Start for the full walkthrough.

Upgrade

Already have Squad? Update Squad-owned files to the latest version without touching your team state:

npx github:bradygaster/squad upgrade

This overwrites squad.agent.md, .ai-team-templates/, and squad workflow files in .github/workflows/. It never touches .ai-team/ β€” your team's knowledge, decisions, and casting are safe.


Known Limitations

  • Experimental β€” API and file formats may change between versions
  • Node 22+ β€” requires Node.js 22.0.0 or later (engines field enforced)
  • GitHub Copilot CLI & VS Code β€” Squad is fully supported on CLI and VS Code (v0.4.0+). For platform-specific feature support (model selection, background mode, SQL tool access), see Client Compatibility Matrix
  • gh CLI required β€” GitHub Issues, PRs, Ralph, and Project Boards all need gh auth login. Project Boards additionally require gh auth refresh -s project
  • Knowledge grows with use β€” the first session is the least capable; agents improve as they accumulate history
  • SSH agent required for install β€” npx github:bradygaster/squad resolves via git+ssh://. If no SSH agent is running, npm's progress spinner hides git's passphrase prompt, making install appear frozen. Fix: start your SSH agent first (ssh-add), or use npx --progress=false github:bradygaster/squad. See #30

Status

🟣 Experimental β€” v0.4.0-dev. Contributors welcome.

Conceived by @bradygaster.

For Tasks:

Click tags to check more tools for each tasks

For Jobs:

Alternative AI tools for squad

Similar Open Source Tools

For similar tasks

For similar jobs