gemini-swarm
Gemini CLI swarm mode extension - orchestrate multiple agents as an autonomous team
Open source Open in the app JSON README (API)
About
Gemini CLI swarm mode extension - orchestrate multiple agents as an autonomous team
Details
- Kind
- Plugins
- Topic
- AI, RAG & memory
- Publisher
- tmdgusya
- Origin
- gemini
- Category
- ferramentas
- Version
- 0.3.2
- Stars
- 14
- Forks
- 3
- Last push
- 2026-03-11T08:21:34Z
- Repository state
- ativo
- Language
- TypeScript
- Added
- 2026-08-30 14:13:39
- Updated
- 2026-08-30 14:13:39
- Origin id
tmdgusya/gemini-swarm
README
# Gemini Swarm
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.
## Prerequisites
- [Gemini CLI](https://github.com/google-gemini/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).
## Installation
```bash
gemini extensions install https://github.com/tmdgusya/gemini-swarm
```
No build step required — bundled with all dependencies.
To verify:
```bash
gemini --list-extensions
# Should show: gemini-swarm
```
## Quick Start
### 1. Start tmux and Gemini
```bash
tmux
gemini
```
### 2. Create tasks and spawn agents
```
> 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
```
### 3. Plan-based execution (recommended for complex tasks)
```
> /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.
### 4. Research-based execution
```
> /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`.
## How It Works
```
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.
## MCP Tools
### Orchestrator Tools
| 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 |
### Agent Tools (used by spawned agents)
| 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 |
### Shared Tools
| 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 |
## Architecture
```
~/.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
```
### Key Design Decisions
- **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
## Troubleshooting
**Agents run as background processes (no tmux panes)**
- Start `tmux` before launching `gemini`
**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`
## Development
```bash
npm install
npm run build # Bundle with esbuild
npm run build:tsc # Type-check only
npm test # Run tests
```
## License
MIT