gemini-swarm

gemini-swarm

Gemini does the writing. Your orchestrator plans and reviews.

gemini-swarm is a Claude Code plugin/skill (portable to other harnesses) that makes Gemini the default writer for substantial work. Whenever a task means writing more than a trivial amount of code or content, your orchestrator splits it into subtasks, fans each one out to a live agy (Antigravity CLI) session running the right Gemini model, and integrates the results — all while its own context stays clean. It also ships gemini-imagegen for generating real images through Gemini's generate_image tool, something Claude can't do on its own.

Contents

New here?

• What it does — the idea, and the four steps it runs
• Why this exists — separate orchestration from execution
• Use cases — is this the right fit for my task?

Installing?

• Getting started — full setup, ~5 min from a clean machine
• Already have agy? Jump to Step 3 — just add the plugin
• Other install methods — plain skill, or another harness

Reference

• Usage & commands · Autonomy modes · Run logs · How it works

---

What it does

The orchestrator:

1. Decomposes a task into independent subtasks (different files, modules, or research topics — no shared-state conflicts),
2. Routes each subtask to the right Gemini model via the Antigravity CLI (agy): it reads the live list of the newest Gemini models from agy models and picks a model and thinking level per subtask, following the model routing guide,
3. Dispatches all subtasks in parallel agy sessions, and
4. Integrates the results, writing a run log to .gemini-swarm/logs/.

The orchestrator model does planning and review; Gemini does the token-heavy bulk work.

---

Why this exists

Large tasks can fill an orchestrator’s context with intermediate output. This plugin separates planning and review from execution: the host agent defines independent tasks, Gemini sessions produce the artifacts, and the host reviews and integrates the results.

Each session writes its output to disk, leaving the orchestrator with a compact status report and an auditable run log. Bulk work goes to a fast model and the hard parts go to the flagship; the orchestrator decides per subtask from what agy offers right now, so a new Gemini release is used as soon as it appears in agy models, with no update to this repository.

Access, quotas, and available tools depend on your Antigravity account. This repository does not provide model access or guarantee a free usage tier.

---

Getting started

You need three things: the Antigravity CLI (agy), a logged-in + trusted workspace, and this plugin. ~5 minutes from a clean machine.

Step 1 — Install the Antigravity CLI (agy)

agy is Google's terminal agent; it's the process that actually runs each Gemini job. Install it with the official one-line script (no Node/Python needed — it's a single Go binary):

# macOS / Linux
curl -fsSL https://antigravity.google/cli/install.sh | bash

# Windows PowerShell
irm https://antigravity.google/cli/install.ps1 | iex

The script drops the binary at ~/.local/bin/agy (macOS/Linux) and adds it to your PATH. Open a new terminal, then confirm it's reachable:

agy --version      # built & tested against agy 1.0.15

If agy: command not found, add its directory to your PATH (export PATH="$HOME/.local/bin:$PATH" in your shell profile) and reopen the terminal.

Step 2 — Log in and trust your project

Run agy once, interactively, inside the project you want to swarm in:

cd /path/to/your/project
agy

On first run it opens Google Sign-In (or prints an authorization URL for remote/SSH sessions — complete it in a local browser). It also asks whether to trust this workspace — say yes. This trust is per-directory, so repeat agy once in each new project. Type /quit (or Ctrl-C) to exit once you're logged in and trusted.

That's the whole agy side. Everything below runs agy for you — you won't open it by hand again.

Step 3: Install the plugin

This is two separate commands — run them one at a time at the Claude Code prompt:

/plugin marketplace add Vallykrie/gemini-swarm-skill

/plugin install gemini-swarm@gemini-swarm-skill

⚠️ Don't paste both onto one line, and don't paste /plugin install … into the "Add Marketplace / Enter marketplace source" box — that field wants only the source (Vallykrie/gemini-swarm-skill). The install is a second, separate step.

This gives you both skills (gemini-swarm, gemini-imagegen), the /gemini-swarm and /gemini-imagegen commands, and the gemini-dispatcher subagent. You're ready — jump to Usage.

---

Keeping the skill updated

Model choice needs no updates. No model names are stored in this repository. Each run, the orchestrator calls scripts/list-models.sh, which reads agy models and keeps only the newest version of each Gemini family, then picks a model per subtask. The dispatcher checks every choice against the same live list and refuses unavailable or superseded models before anything launches. A new Gemini release is used as soon as agy offers it, on every install method.

Skill instructions still need an update. Plugin installs check for a newer release once a day at session start and print the update command when one is available (disable with GEMINI_SWARM_NO_UPDATE_CHECK=1).

For Claude Code marketplace installs, enable updates once: open /plugin, go to Marketplaces, select gemini-swarm-skill, and select Enable auto-update. Third-party marketplace auto-updates are off by default. Restart the session after an update, or run /reload-plugins to load it. See the official update documentation.

To update immediately, run these commands in your terminal:

claude plugin marketplace update gemini-swarm-skill
claude plugin update gemini-swarm@gemini-swarm-skill

Manually copied skill folders are snapshots and do not update themselves. Pull the latest repository with git pull --ff-only and repeat the copy steps below for both complete skill folders. Remove an older manual installation when switching to the plugin to avoid loading conflicting copies.

Maintainers: model releases need no change here. Changes to skill instructions or scripts need a version bump in .claude-plugin/plugin.json, because clients cache plugins by version.

Other install methods

Claude Code — as a plain skill (zero plugin machinery)

Copy the skill folder into your personal skills directory:

git clone https://github.com/Vallykrie/gemini-swarm-skill
cp -r gemini-swarm-skill/skills/gemini-swarm ~/.claude/skills/
cp -r gemini-swarm-skill/skills/gemini-imagegen ~/.claude/skills/

The skill folders are self-contained: each SKILL.md holds the full playbook, references/models.md explains how to choose a model, and scripts/ holds the live model lister (plus the dispatcher for gemini-swarm).

Other harnesses (Codex CLI, OpenCode, Antigravity CLI)

The core logic is one Markdown playbook (skills/gemini-swarm/SKILL.md) plus one shell script. See docs/harnesses.md for thin adapter instructions per harness.

---

Usage

In Claude Code:

/gemini-swarm                 # same as "default"
/gemini-swarm default         # mirror the host agent's current permission mode
/gemini-swarm auto            # force full autonomy (sandboxed) for all agy jobs
/gemini-swarm request         # force request-review for all agy jobs

Then just describe the task:

/gemini-swarm auto Port every module under src/legacy/ to TypeScript and write a migration report.

The orchestrator splits the work into independent subtasks, assigns a model per subtask (never asking you which), launches all of them concurrently, auto-accepts the results, and writes a run log.

You don't need to invoke it explicitly. With the plugin installed, the skill's trigger is delegate by default: any writing work spanning more than one file or more than ~20 lines should activate it, so ordinary requests like "build a todo app" or "add tests for the parser" get written by Gemini with the orchestrator planning and reviewing. A single coherent task is dispatched as a swarm of one — parallel fan-out is an optimization, not a requirement. Explicit phrases ("swarm this across Gemini", "fan this out") also work, with default mode.

Image generation (/gemini-imagegen)

Claude can't generate raster images — Gemini via agy can. The bundled gemini-imagegen skill dispatches an agy session whose generate_image tool creates the image and saves it wherever you ask:

/gemini-imagegen a flat-style logo of a hummingbird in teal and orange, transparent background, save as assets/logo.png

It also triggers implicitly whenever a task needs image assets ("make me a hero image for the landing page") or the user asks to generate/edit an image. Multiple images are dispatched in parallel, one agy job per image, and the orchestrator views each result to verify it matches before delivering.

Use cases: when it pays off

gemini-swarm pays off whenever a task splits into independent chunks that don't share state — so they can run at once without stepping on each other — and the bulk of the work is mechanical enough to hand to Gemini while your orchestrator just plans and reviews.

Scenario: you have a repo with 20 API-route files and no tests. Writing them serially in your main agent would burn its whole context window on boilerplate.

/gemini-swarm auto
Write unit tests for every file in src/routes/. One test file per route,
covering the happy path and the main error cases. Match the existing style
in tests/.

What happens:

1. The orchestrator decomposes it into ~20 independent subtasks (one per route — no two touch the same file, so no conflicts).
2. It routes each using the live model list and the routing guide: simple route tests go to the newest Flash model, while tests for tricky auth or concurrency logic can go to the flagship. It never asks you which.
3. All ~20 agy jobs run in parallel, each writing its own test file directly to disk.
4. The orchestrator integrates: confirms every file landed, writes a run log to .gemini-swarm/logs/, and reports back a short summary — not 20 walls of Gemini output.

Your main agent's context stays clean; the token-heavy grind happened in the Gemini sessions. Other good fits: porting many modules to a new language, generating docstrings across a package, researching several topics at once, refactoring a set of unrelated files. Poor fits: one big file everything edits, or steps that must happen in order — those have no parallelism to exploit.

Autonomy modes

Mode	What the agy jobs get
default	Mirrors the host: if Claude Code is in auto-accept/bypass mode, jobs run with --dangerously-skip-permissions --sandbox; if Claude Code is in review mode, jobs run under agy's configured request-review tool permission.