{
  "markdown": "# Gemini Swarm\n\nA 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.\n\n## Prerequisites\n\n- [Gemini CLI](https://github.com/google-gemini/gemini-cli) installed and configured\n- **tmux** (recommended) — agents spawn as visible tmux panes\n- **Node.js** >= 18\n\n> Without tmux, agents fall back to background processes (no visual panes).\n\n## Installation\n\n```bash\ngemini extensions install https://github.com/tmdgusya/gemini-swarm\n```\n\nNo build step required — bundled with all dependencies.\n\nTo verify:\n\n```bash\ngemini --list-extensions\n# Should show: gemini-swarm\n```\n\n## Quick Start\n\n### 1. Start tmux and Gemini\n\n```bash\ntmux\ngemini\n```\n\n### 2. Create tasks and spawn agents\n\n```\n> Initialize the swarm, create 3 tasks for analyzing auth.ts, db.ts, and api.ts,\n  then spawn 3 agents to work on them.\n```\n\nOr step by step:\n\n```\n> swarm_init\n> swarm_create_tasks with tasks for each module analysis\n> swarm_spawn 3 agents\n> swarm_status\n> swarm_results\n```\n\n### 3. Plan-based execution (recommended for complex tasks)\n\n```\n> /swarm:plan Implement OAuth2 authentication with refresh tokens\n```\n\nThis starts an interactive Q&A to generate a spec and phased plan, then executes each phase with parallel agents and verification checkpoints.\n\n### 4. Research-based execution\n\n```\n> /swarm:research \"React 19 Server Components\"\n```\n\nThis 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`.\n\n## How It Works\n\n```\nOrchestrator                    Coordination Server (HTTP)\n  │                                     │\n  ├─ swarm_init ──────────────────────► Start server\n  ├─ swarm_create_tasks ──────────────► TaskBoard: [task1, task2, task3]\n  ├─ swarm_spawn(3) ──────────────────► Spawn 3 Gemini CLI agents\n  │                                     │\n  │   ┌─── Agent 1 ◄───── task_list ────┤\n  │   │    claim(\"1\") ─────────────────►│ task1: open → claimed\n  │   │    (working...)                 │\n  │   │    complete(\"1\", result) ──────►│ task1: claimed → completed\n  │   │    task_list ──────────────────►│ no more tasks → exit\n  │   │                                │\n  │   ├─── Agent 2 ◄───── claim(\"2\") ──┤ ...\n  │   └─── Agent 3 ◄───── claim(\"3\") ──┤ ...\n  │                                     │\n  ├─ swarm_status ────────────────────► Summary of agents + tasks\n  └─ swarm_results ───────────────────► Completed task results\n```\n\nAgents 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.\n\n## MCP Tools\n\n### Orchestrator Tools\n\n| Tool | Parameters | Description |\n|------|-----------|-------------|\n| `swarm_init` | — | Start coordination server |\n| `swarm_create_tasks` | `tasks[]` | Create tasks on the TaskBoard |\n| `swarm_spawn` | `count`, `role?` | Spawn N agent processes |\n| `swarm_status` | — | Get agent and task status |\n| `swarm_results` | `task_id?` | Collect completed results |\n| `swarm_kill` | `agent?` | Kill specific or all agents |\n| `swarm_plan_execute` | `planDir`, `resumePhase?` | Execute plan phase-by-phase |\n\n### Agent Tools (used by spawned agents)\n\n| Tool | Parameters | Description |\n|------|-----------|-------------|\n| `swarm_task_list` | — | List open tasks |\n| `swarm_task_claim` | `task_id` | Atomically claim a task |\n| `swarm_task_complete` | `task_id`, `result`, `sha?` | Report task completion |\n| `swarm_task_fail` | `task_id`, `error` | Report task failure |\n\n### Shared Tools\n\n| Tool | Parameters | Description |\n|------|-----------|-------------|\n| `swarm_send` | `to`, `message` | Send message to another agent |\n| `swarm_receive` | — | Check message inbox |\n| `swarm_lock` / `swarm_unlock` | `resource` | File-level locking |\n| `swarm_heartbeat` | — | Agent alive signal |\n\n## Architecture\n\n```\n~/.gemini/extensions/gemini-swarm/\n├── gemini-extension.json      # Extension manifest\n├── GEMINI.md                  # Context for Gemini (orchestrator + agent guide)\n├── commands/swarm/            # Slash commands\n│   ├── plan.toml\n│   ├── research.toml\n│   ├── status.toml\n│   ├── results.toml\n│   └── kill.toml\n├── src/                       # TypeScript source\n│   ├── server.ts              # MCP server (thin client → coord server)\n│   ├── coord-server.ts        # HTTP coordination server (TaskBoard, agents, messages, locks)\n│   ├── coord-client.ts        # HTTP client + auto-start\n│   ├── types.ts               # Shared types and API contract\n│   ├── tmux-spawner.ts        # tmux pane lifecycle\n│   ├── plan-parser.ts         # Plan.md parser\n│   └── lock-manager.ts        # File-based locking\n└── dist/                      # Bundled JS (esbuild, zero-install)\n    ├── server.js              # MCP entry point\n    └── coord-server.js        # Coordination server\n```\n\n### Key Design Decisions\n\n- **Pull model**: Agents claim tasks from a shared TaskBoard, not assigned by the orchestrator\n- **HTTP coordination**: All agents connect to the same localhost HTTP server for shared state\n- **Auto-start**: The coordination server starts automatically on first tool call\n- **Heartbeat + auto-release**: Dead agents' tasks are released back to the TaskBoard after 60s\n- **Phase-gating**: Plan execution pauses between phases for verification checkpoints\n\n## Troubleshooting\n\n**Agents run as background processes (no tmux panes)**\n- Start `tmux` before launching `gemini`\n\n**Extension not loading**\n- Verify: `gemini --list-extensions`\n- Reinstall: `gemini extensions install https://github.com/tmdgusya/gemini-swarm`\n\n**Agents not picking up tasks**\n- Check coordination server: `swarm_status`\n- Verify tasks exist: `swarm_task_list`\n\n## Development\n\n```bash\nnpm install\nnpm run build        # Bundle with esbuild\nnpm run build:tsc    # Type-check only\nnpm test             # Run tests\n```\n\n## License\n\nMIT\n",
  "bytes": 6075,
  "sha": "7bcbf3dc2468ae494a366f8c3770a960e34df1304891fd72d249ab6985ea1c64",
  "repo_slug": "tmdgusya/gemini-swarm",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_tmdgusya_gemini_swarm_8923eca7/readme"
}