Agent swarm

Hand work to several AI agents at once. Each agent works on its own copy of your project, on its own branch, so the agents never get in each other's way and never touch your checkout. When an agent finishes, the result is posted to the room and appears in the Runs panel. You review the branch and merge it when you like it.

Supported agents: Claude Code (claude), Antigravity (agy), Codex (codex), Gemini CLI (gemini).

Start a swarm

Open the Swarm task window in any of these ways:

  • Ctrl+Shift+A (also works while a terminal has focus)
  • Swarm task in the room panel header
  • The agent menu (⌄ next to + in the tab bar), then Assign task to agents…
  • Ctrl+P, then :swarm

Then:

  1. Check the Project. It defaults to the project you are in, and the agents work on that repository.
  2. Describe the task. To give each agent its own task, tick One task per line and write one task per line.
  3. Pick one or more agents. Every task goes to every agent you pick, so 3 tasks × 1 agent = 3 runs, and 1 task × 3 agents = 3 runs, which is handy for comparing answers.
  4. Optional: add a check command, such as npm test. A result is accepted only if the check passes in that agent's copy of the project. If it fails, the run is marked failed and you can read why.
  5. Click Start. The Runs panel opens and shows each run live.

The project must be a git repository. Each run starts from your current commit, so commit anything the agents should see first.

From a terminal

deffier swarm "Add input validation to the signup form" --agent agy
deffier swarm "Write tests for utils/date.ts" "Update the README install section" --agent agy --wait
deffier swarm "Fix the failing date test" --agent claude --agent agy --check "npm test" --wait
deffier swarm "Refactor the logger" --agent claude --profile claude2      # run on a specific account
  • Several tasks: each quoted task becomes its own run.
  • --agent: repeat it for several agents. The default is claude.
  • --check: must pass before a result is accepted. You can repeat it.
  • --profile: runs the agent on one of your account profiles (see Account profiles).
  • --wait: follows the runs and prints each result. It exits with 0 only if every run was delivered.

Run it inside your project folder, or pass --project <folder>. The Deffier app must be running, because it does the work; the command only hands it the tasks.

Talk to an agent that is already running

Each agent tab is a live session. To give the agent in a tab its next instruction from a script or from another agent:

deffier send @worker-agy "Now add tests for the new function"
deffier send "claude2 3" "y"            # answer a yes/no question

send types the line into that tab's prompt and presses Enter. Use --no-enter to only type it. Session names are shown in the sidebar and by deffier ls.

Room messages are different. deffier room send … --target @name posts to the room and shows a banner in the target's terminal. Use them for notes and status; use swarm or send when you want an agent to act. The message appears in the Room panel straight away, signed with the sender's session name (t2, worker-agy…). In PowerShell write the target without @ (--target t3) or quote it ('@t3'): an unquoted @t3 is PowerShell syntax and arrives empty.

Wait for another agent. deffier wait t3 returns when t3 is done, or quiet again after it was working. deffier ls shows each session's live state (working, blocked, done, idle), the same as the sidebar.

deffier is a command in every Deffier terminal (PowerShell, cmd and Git Bash).

One agent leads the others

Agents in your project learn these commands from the room protocol: run Sync mesh in the room panel, or deffier mesh sync, and it is written into CLAUDE.md and .gemini/rules. So you can ask a lead agent, for example Claude in one tab:

Split this feature into three independent tasks and hand them to agy with deffier swarm … --wait, then review the three branches and tell me which to merge.

The lead runs deffier swarm, waits for the results, and reviews each one with deffier autopilot diff <run id>.

This was tested for real:

  1. A Claude lead split a feature into two tasks.
  2. It handed both to Antigravity with one deffier swarm --wait; they ran in parallel.
  3. It reviewed each result with deffier autopilot diff.
  4. It recommended merging the good one and not the one whose worker had failed.

The whole thing took about two minutes. If the lead runs with restricted permissions, allow it python …dewwie.py:* (or deffier:*); that one rule covers handing out work and reviewing it.

Results

Where What
Runs panel (robot button, Ctrl+5) Every run: state, the agent's answer, checks, changed files, live output; Cancel
Room A Swarm message when each run is delivered or fails
autopilot/<run id> branch The agent's work as one commit (git log -p autopilot/<run id>)
deffier autopilot runs / show <run id> The same from a terminal

A task that only asks a question (for example "explain this module") is delivered with the answer and no file changes.

Review and merge

From a terminal, or for a lead agent:

deffier autopilot diff <run id>          # what the run changed: files and the diff (read-only)
deffier autopilot diff <run id> --stat   # files only

deffier swarm --wait prints this command for every delivered run.

In the app, open the run in the Runs panel (Ctrl+5) and click it:

  • View changes shows what the agent changed, as a diff.
  • Merge into your branch merges the result branch into the branch you have checked out.
    • The merge commit uses your own git identity.
    • It refuses when your checkout has uncommitted changes. Commit or stash them first.
    • If the result conflicts with your work, the merge is cancelled and nothing changes. The message tells you which files conflict, and you can merge yourself with git merge <branch>.
  • Discard deletes the result branch.

Once you merge or discard, the run shows what you did.

Limits and costs

  • Real agents use your accounts. Each run is a real request on the account that agent CLI is signed in to. Deffier never switches or rotates accounts on its own.
  • Permissions: agents may read and edit files in their own copy of the project. Anything more, such as running shell commands, needs your OK:
    • Claude: when it needs a tool it wasn't given, the run pauses as Parked. The Runs panel shows what it asked for, with Allow and Deny. Allow resumes it with that permission for this run only.
    • Antigravity: runs in accept-edits mode. When it wants to run a command, the run is Parked in the same way. Allow re-runs it with commands allowed for that run only; nothing is saved to your agy settings.
      • If your agy settings already say always proceed, agy runs commands without asking. That is your agy setting, and Deffier respects it.
    • Codex: runs with the workspace-write sandbox.
    • Gemini: runs in auto_edit mode.
    • Claude may run the task's own check commands without asking, so it can verify its work. Nothing broader is allowed in advance.
  • Nothing to show means failed. A run that ends with no answer and no changes is marked failed, with the reason, never "delivered". A failed run always says why. For example: "Your access token could not be refreshed. Please log out and sign in again" means that CLI needs you to sign in again.
  • Temporary provider errors are retried. These include "overloaded", "high demand", rate limits and dropped connections. Deffier waits 30 s, then 2 minutes, and retries on the same account. It never switches accounts. A login error or a quota that is used up is not retried.
  • Cost (Claude). In our tests a small fix cost about $0.40 per run, because of Claude Code's own start-up cost. Cap it with --max-cost 0.5. Leading two agy workers and reviewing their results cost the lead about $0.23.
  • Waiting for you. With --wait, a run that needs a permission prints what it asks for and the deffier autopilot approve <run id> command. In the app, use Allow / Deny in the Runs panel.
  • Each task has a 30-minute limit.
  • Up to 20 tasks × 8 agents per request.
  • The app must stay open. If it closes during a run, that run is marked as interrupted.

This guide is doc/SWARM.md in the Deffier repo.