codex-swarm

Codex Swarm Skill

Claude Opus 4.6 als Oberagent orchestriert N parallele Codex-Agents. Jeder Agent arbeitet isoliert in eigener Git Worktree via tmux (WSL2/Ubuntu).

Architektur

┌──────────────────────────────────────────────────────┐
│  Claude Opus 4.6 (Oberagent)                         │
│  ────────────────────────────                        │
│  1. Task entgegennehmen + Konfiguration parsen       │
│  2. Task in N Sub-Tasks zerlegen (oder N identisch)  │
│  3. N tmux-Panes spawnen mit je einem Codex-Agent    │
│  4. Parallel warten auf Completion                   │
│  5. Ergebnisse sammeln + reviewen + mergen           │
├──────────────────────────────────────────────────────┤
│  tmux session: codex-swarm-<timestamp>               │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐    ┌─────────┐│
│  │ Agent 0 │ │ Agent 1 │ │ Agent 2 │ ...│ Agent N ││
│  │ WT: /0  │ │ WT: /1  │ │ WT: /2  │    │ WT: /N  ││
│  │ Model:  │ │ Model:  │ │ Model:  │    │ Model:  ││
│  │ 5.4-mini│ │ 5.3-cdx │ │ 5.4     │    │ 5.4-mini││
│  └─────────┘ └─────────┘ └─────────┘    └─────────┘│
└──────────────────────────────────────────────────────┘

Konfiguration

Der Swarm wird ueber eine JSON-Konfiguration oder CLI-Flags gesteuert:

CLI-Aufruf

# Einfach: N Agents mit gleichem Task
./scripts/codex-swarm.sh \
  --repo ~/projects/myapp \
  --agents 5 \
  --model gpt-5.4-mini \
  --prompt "Schreibe Unit-Tests fuer alle Dateien in src/utils/"

# Mit Reasoning-Level
./scripts/codex-swarm.sh \
  --repo ~/projects/myapp \
  --agents 3 \
  --model gpt-5.3-codex \
  --reasoning high \
  --prompt "Refactore alle Dateien in src/ zu async/await"

# Pro Agent eigener Task (via JSON-Config)
./scripts/codex-swarm.sh \
  --repo ~/projects/myapp \
  --config swarm-config.json

# Gemischt: verschiedene Modelle
./scripts/codex-swarm.sh \
  --repo ~/projects/myapp \
  --agents 3 \
  --models "gpt-5.4-mini,gpt-5.3-codex,gpt-5.4" \
  --prompt "Implementiere die TODO-Kommentare in diesem Repo"

# Task-Zerlegung: Claude zerlegt automatisch in Sub-Tasks
./scripts/codex-swarm.sh \
  --repo ~/projects/myapp \
  --agents 4 \
  --decompose \
  --prompt "Refactore das gesamte Projekt auf async/await und schreibe Tests"

# Slash-Command (aus Claude Code heraus)
# /codex-swarm --prompt "Write tests for all modules" --agents 5 --decompose yes

JSON-Config (swarm-config.json)

{
  "repo": "/path/to/project",
  "timeout": 600,
  "agents": [
    {
      "name": "tests-utils",
      "model": "gpt-5.4-mini",
      "reasoning": "low",
      "prompt": "Write unit tests for src/utils/"
    },
    {
      "name": "tests-api",
      "model": "gpt-5.3-codex",
      "reasoning": "high",
      "prompt": "Write integration tests for src/api/"
    },
    {
      "name": "refactor-models",
      "model": "gpt-5.4",
      "reasoning": "medium",
      "prompt": "Refactor src/models/ to use dataclasses"
    },
    {
      "name": "docs",
      "model": "gpt-5.4-mini",
      "reasoning": "low",
      "prompt": "Generate docstrings for all public functions"
    }
  ]
}

Ablauf im Detail

Phase 0: Task-Zerlegung (optional, --decompose)

Claude Opus analysiert den High-Level-Task und das Repo, zerlegt ihn in N unabhaengige Sub-Tasks mit passendem Modell und Reasoning-Level pro Agent. Generiert automatisch eine generated-config.json.

# Claude zerlegt "Refactore das gesamte Projekt" in z.B.:
#   Agent 0: "Refactore src/utils/ zu async/await" (gpt-5.4-mini, low)
#   Agent 1: "Refactore src/api/ zu async/await" (gpt-5.3-codex, medium)
#   Agent 2: "Update alle Tests" (gpt-5.4-mini, low)

Phase 1: Setup

1. Konfiguration parsen (CLI-Flags, JSON, oder generierte Config)
2. Validierung: Repo existiert, tmux verfuegbar, codex CLI vorhanden
3. tmux-Session erstellen: codex-swarm-<timestamp>
4. N Git Worktrees erstellen (parallel)
5. Pro Agent: safe.directory konfigurieren

Phase 2: Spawn (Parallel via tmux)

Fuer jeden Agent i=0..N-1:

tmux send-keys -t "codex-swarm-$TS:$i" \
  "cd $WORKTREE_DIR && codex exec --sandbox workspace-write \
   --model $MODEL '$PROMPT' > $OUTPUT_DIR/agent-$i.txt 2>&1; \
   echo DONE > $OUTPUT_DIR/agent-$i.done" Enter

Phase 3: Wait (Polling)

Timeout: Standardmaessig 600s (10 min), konfigurierbar via --timeout.

Phase 4: Collect

1. Diffs aus allen Worktrees extrahieren (git add -A && git diff --cached HEAD)
2. Agent-Outputs sammeln
3. Ergebnisse in output/swarm-<timestamp>/ ablegen

Phase 5: Review (Claude Opus 4.6)

Claude Opus reviewed automatisch alle gesammelten Diffs:

1. Pro Agent: Korrektheit und Vollstaendigkeit der Aenderungen
2. Konflikte: Gleiche Dateien von mehreren Agents geaendert?
3. Qualitaet: Bugs, fehlende Error-Handling, Style-Issues
4. Merge-Empfehlung: Safe-to-merge vs. manuelles Review noetig
5. Ergebnis in review.md gespeichert

Phase 6: Cleanup

Worktrees loeschen, tmux-Session beenden.

output/swarm-<timestamp>/
├── generated-config.json    # Task-Zerlegung (bei --decompose)
├── agent-0.txt              # Stdout von Agent 0
├── agent-0.diff             # Git diff von Agent 0
├── agent-0.meta.json        # Modell, Reasoning, Worktree
├── ...
├── summary.md               # Oberagent-Zusammenfassung
└── review.md                # Claude Opus Review

Modell-Optionen

Modell	Staerken	Empfehlung
gpt-5.4	Neuestes Frontier-Modell, bestes Reasoning	Komplexe Features, Architektur-Tasks
gpt-5.4-mini	Schnell, guenstig, solides Reasoning	Tests, Docs, Linting, Boilerplate
gpt-5.3-codex	Coding-optimiert (Default)	Refactoring, Implementierung, Bug-Fixes
gpt-5.2-codex	Aelterer Codex, stabil	Fallback bei 5.3 Problemen
gpt-5.2	General-purpose	Nicht-Code Tasks
gpt-5.1-codex-max	Max-Kontext, grosse Codebases	Mono-Repo Refactoring
gpt-5.1-codex-mini	Minimal, nur medium/high	Budget-Option

Hinweis: Mit ChatGPT-Abo (kein API-Key) — o3/o4-mini sind NICHT verfuegbar.

Reasoning Levels

Alle Modelle unterstuetzen konfigurierbare Reasoning-Tiefe:

Level	Beschreibung	Empfehlung
low	Schnell, minimales Reasoning	Mechanische Tasks (Linting, Docs, Boilerplate)
medium	Balanciert (Default)	Alltaegliche Coding-Tasks
high	Tiefes Reasoning	Komplexe Refactorings, Bug-Fixes
xhigh	Maximum Reasoning	Architektur-Entscheidungen, Security-Reviews

CLI: --reasoning <level> oder per Agent in JSON-Config: "reasoning": "high"

Voraussetzungen

• WSL2/Ubuntu mit tmux installiert
• codex CLI authentifiziert (OAuth via Desktop App)
• claude CLI authentifiziert (Max Plan)
• Git Repo als Zielverzeichnis

Limits und Hinweise

• Jeder Agent = eigenes Codex-Kontextfenster + API-Call
• Bei N=10 Agents: 10x parallele Codex-Sessions
• tmux-Sessions bleiben nach Fehler bestehen → manuell killen: tmux kill-session -t codex-swarm-*
• Worktrees werden nach Completion geloescht (Amnesie)
• Bei Merge-Konflikten: Claude Opus markiert, User entscheidet
• Codex --sandbox workspace-write erlaubt nur Schreiben im Worktree, kein Netzwerk

Wann diesen Skill nutzen

JA — Swarm nutzen wenn:

• Viele unabhaengige Tasks parallelisiert werden koennen
• Grosses Refactoring ueber viele Dateien/Module
• Test-Generierung fuer gesamtes Projekt
• Bulk-Operationen (Docs, Linting, Migration)

NEIN — Einzelagent nutzen wenn:

• Tasks voneinander abhaengen (sequentiell)
• Nur 1-2 Dateien betroffen
• Komplexes Reasoning noetig (→ Claude direkt)