Skip to content
Gee-Code

Flights & Swarms

Gee-Code provides two orchestration patterns for running multiple agents: Flights for parallel execution of the same agent type, and Swarms for coordinating clusters of different agent types with dependencies.

Flights

Section titled “Flights”

A flight runs multiple instances of the same agent in parallel on the same task, then synthesizes their results. Each agent explores independently, giving you diverse perspectives or thorough coverage.

How It Works

Section titled “How It Works”
           FlightOrchestrator
┌──────────────────────────────────┐
│  1. Create N members (same agent)│
│  2. Run all in parallel          │
│  3. Collect results              │
│  4. Synthesize into one response │
└──────────────────────────────────┘

Running a Flight

Section titled “Running a Flight”
/flight explore "Analyze the authentication flow" --count 3

This launches 3 explore agents in parallel, each independently analyzing the auth flow, then synthesizes their findings into a single response.

Flight Lifecycle

Section titled “Flight Lifecycle”
  1. PENDING — flight created, members initialized
  2. RUNNING — members executing in parallel
  3. SYNTHESIZING — all members done, synthesis agent combining results
  4. COMPLETED — final result available

Flight Templates

Section titled “Flight Templates”

Save reusable configurations as JSON:

{
  "name": "deep-review",
  "agent_type": "review",
  "count": 3,
  "task_template": "Review {mission} focusing on code quality, security, and performance",
  "synthesis_enabled": true
}

Templates are stored in .gee/flights/ (project) or ~/.gee-code/flights/ (global).

Swarms

Section titled “Swarms”

A swarm coordinates multiple clusters of agents working together on a mission. Unlike flights (same agent, same task), swarms use different agent types organized into clusters with dependencies between them.

How It Works

Section titled “How It Works”
              SwarmOrchestrator
┌──────────────────────────────────────┐
│  1. AI planner generates cluster tasks│
│  2. Sort clusters by dependencies    │
│  3. Execute in dependency order      │
│  4. Pass results to dependent clusters│
│  5. Synthesize all cluster results   │
└──────────────────────────────────────┘

Swarm Definition

Section titled “Swarm Definition”
{
  "name": "code-review",
  "description": "Multi-perspective code review",
  "mission_planner": "architect",
  "synthesis_agent": "synthesis",
  "clusters": [
    {
      "id": "analysis",
      "name": "Code Analysis",
      "agents": ["explore"],
      "count_per_agent": 2,
      "task_mode": "auto"
    },
    {
      "id": "security",
      "name": "Security Review",
      "agents": ["review"],
      "dependencies": ["analysis"],
      "task_mode": "auto"
    },
    {
      "id": "recommendations",
      "name": "Recommendations",
      "agents": ["architect"],
      "dependencies": ["analysis", "security"],
      "task_mode": "template",
      "task_template": "Based on: {analysis_result}\nSecurity: {security_result}\nRecommend: {mission}"
    }
  ]
}

Running a Swarm

Section titled “Running a Swarm”
/swarm code-review "Review the authentication module"
  1. PLANNING — AI planner generates tasks for each cluster
  2. RUNNING — clusters execute in dependency order
  3. SYNTHESIZING — synthesis agent combines all results
  4. COMPLETED — final synthesis available

Cluster Configuration

Section titled “Cluster Configuration”
FieldDescription
idUnique identifier for dependency references
agentsAgent types to use
count_per_agentInstances per agent (>1 triggers a flight within the cluster)
dependenciesCluster IDs that must complete first
task_mode"auto" (AI-planned) or "template" (string interpolation)

Flights vs Swarms

Section titled “Flights vs Swarms”
AspectFlightSwarm
Agent typesSingle type, multiple instancesMultiple types in clusters
CoordinationIndependent parallelDependencies between clusters
PlanningSame task for allAI-planned per-cluster tasks
Use caseDiverse perspectives on one taskComplex multi-phase missions
ResultsSingle synthesisHierarchical synthesis

Storage

Section titled “Storage”

Templates and definitions are loaded from (in priority order):

  1. Mode-specific — .gee/modes/{mode}/flights/ or swarms/
  2. Project — .gee/flights/ or .gee/swarms/
  3. User global — ~/.gee-code/flights/ or swarms/
  4. Built-in — package-included templates

Next Steps

Section titled “Next Steps”