A Gemini CLI extension that orchestrates multiple Gemini agents as an autonomous team. Agents claim tasks from a shared TaskBoard, execute them in parallel, and report results — inspired by Claude Code's Agent Teams.
- Gemini CLI installed and configured
- tmux (recommended) — agents spawn as visible tmux panes
- Node.js >= 18
Without tmux, agents fall back to background processes (no visual panes).
gemini extensions install https://github.com/tmdgusya/gemini-swarmNo build step required — bundled with all dependencies.
To verify:
gemini --list-extensions
# Should show: gemini-swarmtmux
gemini> Initialize the swarm, create 3 tasks for analyzing auth.ts, db.ts, and api.ts,
then spawn 3 agents to work on them.
Or step by step:
> swarm_init
> swarm_create_tasks with tasks for each module analysis
> swarm_spawn 3 agents
> swarm_status
> swarm_results
> /swarm:plan Implement OAuth2 authentication with refresh tokens
This starts an interactive Q&A to generate a spec and phased plan, then executes each phase with parallel agents and verification checkpoints.
> /swarm:research "React 19 Server Components"
This starts an interactive Q&A to define the research scope, spawns researcher agents to gather information in parallel, and finally synthesizes all findings into a consolidated report.md.
Orchestrator Coordination Server (HTTP)
│ │
├─ swarm_init ──────────────────────► Start server
├─ swarm_create_tasks ──────────────► TaskBoard: [task1, task2, task3]
├─ swarm_spawn(3) ──────────────────► Spawn 3 Gemini CLI agents
│ │
│ ┌─── Agent 1 ◄───── task_list ────┤
│ │ claim("1") ─────────────────►│ task1: open → claimed
│ │ (working...) │
│ │ complete("1", result) ──────►│ task1: claimed → completed
│ │ task_list ──────────────────►│ no more tasks → exit
│ │ │
│ ├─── Agent 2 ◄───── claim("2") ──┤ ...
│ └─── Agent 3 ◄───── claim("3") ──┤ ...
│ │
├─ swarm_status ────────────────────► Summary of agents + tasks
└─ swarm_results ───────────────────► Completed task results
Agents autonomously pull tasks from the TaskBoard (not pushed by the orchestrator). If there are more tasks than agents, agents pick up remaining tasks after completing their first one.
| Tool | Parameters | Description |
|---|---|---|
swarm_init |
— | Start coordination server |
swarm_create_tasks |
tasks[] |
Create tasks on the TaskBoard |
swarm_spawn |
count, role? |
Spawn N agent processes |
swarm_status |
— | Get agent and task status |
swarm_results |
task_id? |
Collect completed results |
swarm_kill |
agent? |
Kill specific or all agents |
swarm_plan_execute |
planDir, resumePhase? |
Execute plan phase-by-phase |
| Tool | Parameters | Description |
|---|---|---|
swarm_task_list |
— | List open tasks |
swarm_task_claim |
task_id |
Atomically claim a task |
swarm_task_complete |
task_id, result, sha? |
Report task completion |
swarm_task_fail |
task_id, error |
Report task failure |
| Tool | Parameters | Description |
|---|---|---|
swarm_send |
to, message |
Send message to another agent |
swarm_receive |
— | Check message inbox |
swarm_lock / swarm_unlock |
resource |
File-level locking |
swarm_heartbeat |
— | Agent alive signal |
~/.gemini/extensions/gemini-swarm/
├── gemini-extension.json # Extension manifest
├── GEMINI.md # Context for Gemini (orchestrator + agent guide)
├── commands/swarm/ # Slash commands
│ ├── plan.toml
│ ├── research.toml
│ ├── status.toml
│ ├── results.toml
│ └── kill.toml
├── src/ # TypeScript source
│ ├── server.ts # MCP server (thin client → coord server)
│ ├── coord-server.ts # HTTP coordination server (TaskBoard, agents, messages, locks)
│ ├── coord-client.ts # HTTP client + auto-start
│ ├── types.ts # Shared types and API contract
│ ├── tmux-spawner.ts # tmux pane lifecycle
│ ├── plan-parser.ts # Plan.md parser
│ └── lock-manager.ts # File-based locking
└── dist/ # Bundled JS (esbuild, zero-install)
├── server.js # MCP entry point
└── coord-server.js # Coordination server
- Pull model: Agents claim tasks from a shared TaskBoard, not assigned by the orchestrator
- HTTP coordination: All agents connect to the same localhost HTTP server for shared state
- Auto-start: The coordination server starts automatically on first tool call
- Heartbeat + auto-release: Dead agents' tasks are released back to the TaskBoard after 60s
- Phase-gating: Plan execution pauses between phases for verification checkpoints
Agents run as background processes (no tmux panes)
- Start
tmuxbefore launchinggemini
Extension not loading
- Verify:
gemini --list-extensions - Reinstall:
gemini extensions install https://github.com/tmdgusya/gemini-swarm
Agents not picking up tasks
- Check coordination server:
swarm_status - Verify tasks exist:
swarm_task_list
npm install
npm run build # Bundle with esbuild
npm run build:tsc # Type-check only
npm test # Run testsMIT