copilot-teams

Orchestrate teams of GitHub Copilot CLI agents working in parallel — like Claude Code's Agent Teams, but for Copilot.

How It Works

copilot-teams uses the @github/copilot-sdk to run multiple Copilot sessions in a single process. A lead agent analyzes your request, breaks it into tasks, spawns teammate agents with specialized roles, and coordinates their work — all streaming to your terminal in real time.

🤖 copilot-teams > Build an invoice API with Express and PDF generation.

[lead] 📋 create_task "Create src/routes/invoices.ts" ✓
[lead] 📋 create_task "Create src/services/pdf.ts" ✓
[lead] 🚀 spawn_teammate api-developer ✓
[lead] 🚀 spawn_teammate pdf-engine ✓
[api-developer] 📝 write src/routes/invoices.ts ✓
[api-developer] 💻 shell $ npm install express ✓
[pdf-engine] 📝 write src/services/pdf.ts ✓
[pdf-engine] 💬 send_message → lead ✓

Prerequisites

• Node.js 22.5+ (required — the Copilot CLI engine uses node:sqlite)
• An active GitHub Copilot subscription

The Copilot CLI engine is bundled via @github/copilot-sdk — you do not need to install copilot separately.

Installation

From npm

npm install -g copilot-teams

From source

git clone https://github.com/AbhimanyuAryan/copilot-teams.git
cd copilot-teams
npm install
npm run build
npm link

Usage

# From any project directory
copilot-teams

# Custom team name and model
copilot-teams --name my-project --model gpt-5

# Skip prerequisite checks
copilot-teams --skip-checks

Interactive Commands

Once running, type naturally to talk to the lead agent. It will create tasks, spawn teammates, and coordinate their work.

| Command | Description | |----------|----------------------------------| | /team | Show team status and task summary | | /tasks | Show detailed task list | | /help | Show available commands | | /quit | Shut down team and exit |

Example

🤖 copilot-teams > Review PR #142 with a team: one agent on security,
                    one on performance, one on test coverage.

The lead will:

1. Create concrete tasks with file paths
2. Spawn 3 teammate agents with specialized roles
3. Teammates claim tasks, write code, run commands
4. Lead coordinates and synthesizes a final review

Architecture

┌──────────────────────────────────────────┐
│            Single CopilotClient          │
│                                          │
│  ┌──────────┐  ┌──────────┐ ┌─────────┐ │
│  │ Lead     │  │ Teammate │ │Teammate │ │
│  │ Session  │  │ Session  │ │Session  │ │
│  └────┬─────┘  └────┬─────┘ └───┬─────┘ │
│       │              │           │       │
│  ┌────┴──────────────┴───────────┴────┐  │
│  │        Message Bus + Tasks         │  │
│  └────────────────────────────────────┘  │
└──────────────────────────────────────────┘
         ▲ streaming output ▼
      ┌──────────────────────┐
      │   Your Terminal      │
      │  color-coded output  │
      └──────────────────────┘

• Lead Session — user-facing, has team management + coordination tools
• Teammate Sessions — run on the same client, stream output with colored [name] prefixes
• Message Bus — relays messages between agents via session.send()
• Task Manager — shared JSON task list at ~/.copilot-teams/{team}/tasks.json
• Session Logger — animated spinners, tool icons, and progress indicators

All coordination happens through custom tools injected via the SDK's defineTool().

Configuration

| Option | Default | Description | |-----------------|---------------------|--------------------------| | --name | default | Team name (for storage) | | --model | claude-sonnet-4.5 | Lead agent model | | --skip-checks | false | Skip prerequisite checks |

Team configs are stored at ~/.copilot-teams/{team-name}/config.json.

Development

Requires Bun for local development:

bun install
bun run dev          # watch mode
bun run typecheck    # type checking
bun run build        # build for npm

Limitations

• Max 4 teammates per session
• Each teammate = separate Copilot session counting against your premium request quota
• No nested teams (teammates can't spawn sub-teams)
• No session resume across restarts

License

MIT