Anyone who has tried running three AI coding tabs against the same folder at the same time knows how quickly enthusiasm turns into chaos. Agent A edits a shared TypeScript interface while Agent B is halfway through running Vite, Agent C reverts package.json, and twenty minutes later your working tree looks like a merge-conflict crime scene. Google Antigravity's native /swarm architecture was engineered specifically to solve that coordination problem.
Instead of treating multi-agent coding as "open four chat windows and pray," Antigravity builds orchestration around three primitives that mirror how real human engineering teams ship software: a shared public message board, isolated share and branch workspaces, and per-worker model pinning across all sixteen model configurations in the Antigravity roster.
Recent updates in the agy CLI and Antigravity IDE—including the coordinator's "queen bee" header indicator and live animated worker cards in Kitty and Ghostty terminals—make watching a swarm execute genuinely fun. That said, swarms are also quota-heavy. Spawn five heavyweight agents without clear file boundaries, and you will burn half your daily token allowance untangling circular conversations.
Here is our battle-tested playbook for when a multi-agent swarm actually beats a single agent, how to assign the right models to each seat at the table, and how to land clean, verified code every time.
Rule #1: Know When NOT to Spin Up a Swarm
Before spawning a single helper, apply the Two-Minute Coupling Test. If three steps touch the exact same 200-line controller and each step depends directly on the output of the step before it, a single agent running on Gemini 4 Argon (Medium) or Gemini 4 Carbon (Medium) will finish faster, cheaper, and with zero communication overhead.
Swarms earn their keep in three specific topologies:
- Clean Horizontal Slices: Building a new Billing API backend (
app/Services/Billing/), a React Settings dashboard (resources/js/Pages/Billing/), and a Stripe webhook test suite (tests/Feature/Billing/) simultaneously where the JSON contract is agreed up front. - Sharded Repo-Wide Migrations: Updating 60 legacy controllers or auditing 12 microservice folders in parallel slices (
worker-1 through worker-4). - Adversarial Builder + Verifier ("Second Pair of Eyes"): Having one model implement a security-critical feature while a different model family audits the diff cold with read-only permissions.
Figure 2: Successful multi-agent swarms succeed or fail before a single worker spawns—clean module ownership and non-overlapping file contracts prevent merge collisions.
Understanding Workspace Modes: inherit vs. share vs. branch
The single most important parameter when adding a worker to an Antigravity swarm is workspace. Pick the wrong one and parallel authors will step on each other's lockfiles and build artifacts:
| Workspace Mode | How Storage Works Under the Hood | Best Assigned Role | Crucial Cleanup Rule |
|---|
inherit (Default) | Operates directly inside the coordinator's active working copy | Read-only scouts, security auditors, documentation researchers, and test verifiers | Zero merge needed; never assign two concurrent file-writing authors to inherit |
share | Creates an independent working copy sharing the underlying Git/Mercurial object store (like git worktree) | Parallel feature authors editing or building code at the same time | Merge or land the branch BEFORE calling kill, as killing a worker deletes its workspace |
branch | Creates a fully isolated clone branched from the parent workspace | Heavy dependency experiments, destructive schema tests, or native build toolchains | Land committed work into your main working copy first before terminating the worker |
Look closely at that cleanup column: in Antigravity, waiting workers sleep on the message board at zero token cost until someone @mentions them, whereas kill permanently ends the worker and deletes its share or branch directory. Never use kill as a pause button—always merge the worker's commits into your coordinator branch and run final tests before retiring the roster.
The "Dream Team" 4-Agent Swarm Blueprint
Because Antigravity lets you pin each swarm worker to a distinct model and reasoning effort tier, you can balance both technical strengths and model-family quotas simultaneously. Here is a four-seat architecture we use repeatedly for complex full-stack features:
┌──────────────────────────────────────────┐
│ COORDINATOR ("Queen Bee") │
│ Model: Gemini 4 Carbon (Medium / High) │
│ Owns: API Contract, Merges & Final Gate │
└───────┬───────────────┬──────────────┬───┘
│ │ │
┌────────────────▼──┐ ┌──────▼───────────┐ └──────────────▼────────────┐
│ @backend-author │ │ @ui-author │ │ @security-verifier │
│ Gemini 4 Argon │ │ Claude Sonnet 5.5│ │ Gemini 4 Carbon (High) │
│ Tier: Medium │ │ Tier: Medium │ │ Workspace: inherit (Read) │
│ Workspace: share │ │ Workspace: share │ │ Audits merged diff & runs │
│ Owns: app/, tests/│ │ Owns: resources/ │ │ edge-case exploit checks │
└───────────────────┘ └──────────────────┘ └───────────────────────────┘
Why does this specific cross-model pairing work so well?
@backend-author on Gemini 4 Argon (Medium) chews through database migrations, Eloquent models, service classes, and PHPUnit tests rapidly inside its own share worktree using Argon's 1M context window.@ui-author on Claude Sonnet 5.5 (Medium) works simultaneously in a separate share worktree, crafting responsive React/Inertia pages with crisp typography, keyboard accessibility, and loading skeletons—drawing from Anthropic's quota pool while Argon uses Gemini's.@security-verifier on Gemini 4 Carbon (High) stays asleep (waiting) until both branches are merged, then wakes up on @security-verifier to audit authorization policies, N+1 query risks, and race conditions with fresh eyes (zero sunk-cost bias from having written the code!).
Guarding Autonomous Swarms with PreInvocation & Stop Hooks
When four agents are executing terminal commands across shared worktrees, deterministic guardrails matter more than polite system prompts. Recent Antigravity CLI and IDE updates introduced two hook enhancements every team lead should configure in .agents/:
Figure 3: Setting workspace:"share" gives each parallel author agent an isolated working copy backed by your shared repository store—eliminating mid-build file overwrites.
PreInvocation terminationBehavior: "terminate": Inspects outbound prompts or tool contexts before model invocation and cleanly halts the turn if an agent accidentally attempts to read .env production secrets or touch restricted deployment scripts.Stop Hook continuation_active Guard: Prevents infinite recursive verification loops when automated lint/test hooks re-prompt an agent on failure.
Writing Briefs That Prevent Endless Agent Chatter
Because a freshly spawned worker sees none of your private coordinator chat unless you fork history (fork: "coordinator"), its public @mention brief on the board is its entire world. Every effective swarm brief answers four questions in plain bullets:
- Exact files/directories owned (and which files are strictly off-limits).
- Exact JSON/TypeScript contract shared with sibling workers.
- Verification command required (e.g.,
php artisan test --compact --filter=BillingTest must pass green). - Definition of Done: Commit cleanly to your local branch and post a concise summary of changed files and test output back to
@coordinator.
Keep briefs tight, merge methodically, and multi-agent swarms turn full-day feature sprints into focused forty-minute builds.
Common Swarm Anti-Patterns (and How Senior Leads Fix Them)
Even experienced developers stumble into a few classic traps during their first week running parallel agent teams. Watching out for these four anti-patterns will save both your git history and your weekly token budget:
Figure 4: Pairing a Claude Sonnet 5.5 or Gemini 4 Argon builder with an independent Gemini 4 Carbon (High) verifier catches subtle edge cases before code ever hits human PR review.
- The "Overlapping Shared File" Collision: Two workers in separate
share workspaces both decide to register new routes at the bottom of routes/web.php or append keys to lang/en/messages.json. Fix this by keeping top-level wiring files (routes/web.php, package.json, AppServiceProvider.php) exclusively in the Coordinator's hands—instructing feature workers to create self-contained controllers, components, and tests, then report the exact one-line route registration back on the message board. - Spawning Five Agents Before Locking the Schema: If
@ui-author assumes an API returns invoice_total_cents while @backend-author names the column amount_due, you pay twice to rewrite the frontend. Always have the Coordinator draft and post the exact JSON payload contract or TypeScript type definition first before waking parallel builders. - Using Heavy Frontier Reasoning for Mechanical Tasks: Pinning four homogeneous workers to
Gemini 4 Carbon (High) just to add missing alt attributes across forty Blade templates burns premium reasoning budget needlessly. Reserve Carbon for architectural coordination and adversarial verification while assigning mechanical sharded slices to Gemini 3.8 Flash or Gemini 4 Argon (Low). - Forgetting Post-Merge Integration Tests: Individual unit tests can pass green inside isolated
share branches while still breaking when combined—for instance, if a backend middleware change alters Inertia shared props expected by the new frontend page. Always run one final full-suite verification pass in the Coordinator's merged working tree before killing worker workspaces.
Frequently Asked Questions (FAQ)
Do waiting workers on the Antigravity /swarm board consume tokens while idle?
No. A worker in the waiting state is asleep on the shared message board and consumes zero tokens and zero quota until another member posts a message that wakes it up.
Should I kill and re-add a swarm worker if its model runs out of quota mid-task?
Never kill and add to change models—doing so destroys the worker's conversation context and deletes its share or branch workspace! Instead, use the swarm model action to switch a waiting worker to another model (for example, from gemini-4-argon-medium to claude-sonnet-5-5-medium), preserving its full history and uncommitted files.
How many parallel swarm agents should I run on a typical feature?
For most real-world engineering tasks, 2 to 4 focused workers (such as backend author, frontend author, and independent verifier) hit the sweet spot. Beyond 5 concurrent writers, integration and merge review overhead usually outweighs parallel speed gains.