Claude Code Agent Teams einrichten, mehrere Sessions die sich gegenseitig zuarbeiten

Subagents kennst Du vielleicht schon. Du gibst dem Hauptagenten eine Aufgabe, der spawnt einen fokussierten Worker, der arbeitet in seinem eigenen Kontext und meldet am Ende ein Ergebnis zurück. Funktioniert gut für abgegrenzte Jobs. Agent Teams sind etwas anderes. Hier laufen mehrere vollwertige Claude-Code-Sessions gleichzeitig, jede mit eigenem Kontextfenster, und sie reden direkt miteinander statt nur an den Chef zu berichten. Eine Session ist der Team-Lead, koordiniert, verteilt Tasks und fasst am Ende zusammen. Die anderen sind Teammates und können sich gegenseitig widersprechen, Hypothesen testen, Befunde austauschen. Das Feature ist experimentell und standardmäßig aus. Dieses Playbook zeigt wie ich es scharf schalte und wann es den deutlich höheren Token-Verbrauch wert ist.

1. Verstehen wann ein Team besser ist als ein Subagent

Der wichtigste Schritt passiert vor dem Setup, nämlich die Entscheidung ob Du überhaupt ein Team brauchst. Faustregel aus der Doku, Agent Teams glänzen wenn parallele Exploration echten Mehrwert bringt. Vier Szenarien, in denen sie sich lohnen, Research und Review wo mehrere Teammates verschiedene Aspekte gleichzeitig untersuchen und sich danach challengen. Neue Module wo jeder ein eigenes Stück baut ohne dem anderen auf die Füße zu treten. Debugging mit konkurrierenden Hypothesen, jeder testet eine andere Theorie. Und Cross-Layer-Arbeit die Frontend, Backend und Tests gleichzeitig anfasst.

Wofür Du KEIN Team nimmst, sequentielle Aufgaben, Edits an derselben Datei, Arbeit mit vielen Abhängigkeiten. Da ist eine einzelne Session oder ein Subagent effektiver und billiger. Teams kosten Koordinations-Overhead und deutlich mehr Tokens, jeder Teammate ist eine eigene Claude-Instanz mit eigenem Kontext.

2. Das Feature aktivieren

Agent Teams sind disabled by default. Du schaltest sie über die Environment-Variable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS ein, entweder direkt in Deiner Shell oder in der settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Ich nehme den settings.json-Weg, dann ist es projektweit stabil und ich vergesse es nicht beim nächsten Terminal. Wenn Du es nur mal ausprobieren willst, setz die Variable im Shell-Export und starte Claude Code neu. Da es experimentell ist, kann sich das Verhalten zwischen Versionen ändern, also nicht wundern wenn ein Update etwas verschiebt.

3. Das erste Team starten

Nach dem Aktivieren gibst Du Claude in normaler Sprache die Aufgabe und beschreibst die Team-Struktur. Kein Spezial-Command, einfach ein Prompt. Beispiel aus der Doku das gut funktioniert weil die drei Rollen unabhängig sind:

Ich entwerfe ein CLI-Tool das TODO-Kommentare im Codebase trackt.
Erstell ein Agent Team das das aus verschiedenen Winkeln beleuchtet,
einer auf UX, einer auf technische Architektur, einer als Advocatus Diaboli.

Claude baut daraufhin ein Team mit geteilter Task-Liste, spawnt für jede Perspektive einen Teammate, lässt sie das Problem erkunden, fasst die Befunde zusammen und räumt das Team am Ende wieder auf. Wichtig, Claude erstellt nie unaufgefordert ein Team. Entweder Du fragst danach, oder Claude schlägt es vor und Du bestätigst.

4. Die Anzeige steuern, in-process oder Split-Panes

Es gibt zwei Display-Modi. In-process bedeutet, alle Teammates laufen in Deinem Haupt-Terminal, Du blätterst mit Shift+Down durch sie durch und tippst direkt los um einem eine Nachricht zu schicken. Funktioniert in jedem Terminal ohne Zusatz-Setup. Split-Panes gibt jedem Teammate ein eigenes Pane, Du siehst alle Outputs gleichzeitig und klickst in ein Pane um direkt zu interagieren. Das braucht aber tmux oder iTerm2.

Default ist auto, das nimmt Split-Panes wenn Du eh schon in einer tmux-Session sitzt, sonst in-process. Wenn Du fest einen Modus willst, setz teammateMode in ~/.claude/settings.json:

{
  "teammateMode": "in-process"
}

Für eine einzelne Session geht auch das Flag claude --teammate-mode in-process. Für Split-Panes brauchst Du tmux oder iTerm2 mit installiertem it2 CLI, bei iTerm2 musst Du zusätzlich die Python API unter Settings, General, Magic aktivieren. Ich fahre meistens in-process, das spart mir das tmux-Geraffel und reicht für drei bis vier Teammates locker.

5. Anzahl und Modell der Teammates festlegen

Claude entscheidet selbst wie viele Teammates es spawnt, basierend auf der Aufgabe. Du kannst es aber genau vorgeben:

Erstell ein Team mit 4 Teammates die diese Module parallel refactoren.
Nutz Sonnet fuer jeden Teammate.

Ein Detail das oft übersehen wird, Teammates erben standardmäßig NICHT die /model-Auswahl des Leads. Wenn Du willst dass alle dem Lead-Modell folgen, stell unter /config die Option Default teammate model auf Default, also leader's model. Sonst laufen Teammates eventuell auf einem anderen Modell als gedacht, und bei vier parallelen Opus-Teammates merkst Du das spätestens an der Rechnung.

6. Plan-Approval für riskante Aufgaben erzwingen

Bei heiklen Änderungen kannst Du verlangen dass ein Teammate erst plant bevor er etwas anfasst. Der arbeitet dann im read-only Plan-Mode bis der Lead seinen Ansatz absegnet:

Spawn einen Architect-Teammate der das Auth-Modul refactored.
Verlang Plan-Approval bevor er irgendeine Aenderung macht.

Wenn der Teammate fertig geplant hat, schickt er eine Plan-Approval-Request an den Lead. Der prüft und genehmigt oder lehnt mit Feedback ab. Bei Ablehnung bleibt der Teammate im Plan-Mode, überarbeitet und reicht neu ein. Der Lead entscheidet autonom, Du beeinflusst ihn über Kriterien im Prompt, etwa "genehmige nur Pläne mit Test-Coverage" oder "lehn alles ab das das DB-Schema anfasst". Wer Plan-Mode noch nicht im Griff hat, sollte vorher den Plan-Mode-Playbook durchgehen, das Prinzip ist dasselbe nur hier auf einen Teammate angewandt.

7. Direkt mit einzelnen Teammates reden

Jeder Teammate ist eine vollständige, unabhängige Claude-Code-Session. Du kannst jeden direkt anschreiben um Zusatz-Anweisungen zu geben, Rückfragen zu stellen oder den Kurs zu ändern. Im In-process-Modus blätterst Du mit Shift+Down durch die Teammates und tippst dann die Nachricht. Enter zeigt die Session eines Teammates, Escape unterbricht seinen aktuellen Turn, Ctrl+T schaltet die Task-Liste ein und aus. Nach dem letzten Teammate springt Shift+Down zurück zum Lead. Im Split-Pane-Modus klickst Du einfach ins jeweilige Pane.

Das ist der eigentliche Unterschied zu Subagents. Bei einem Subagent kannst Du während der Arbeit nicht reingreifen, der läuft durch und meldet zurück. Beim Teammate kannst Du mitten in die laufende Session funken.

8. Tasks verteilen und das Team kommunizieren lassen

Die geteilte Task-Liste koordiniert die Arbeit. Tasks haben drei Zustände, pending, in progress, completed. Sie können voneinander abhängen, eine pending Task mit offenen Dependencies kann erst geclaimt werden wenn die Vorgänger fertig sind. Der Lead kann Tasks explizit zuweisen ("gib Task X an Teammate Y"), oder Teammates self-claimen, nach Abschluss schnappt sich ein Teammate von selbst die nächste freie, nicht blockierte Task. Damit nicht zwei gleichzeitig dieselbe Task greifen, nutzt das System File-Locking.

Die Kommunikation läuft über eine Mailbox. Nachrichten werden automatisch zugestellt, der Lead muss nicht pollen. Wenn ein Teammate fertig ist und stoppt, meldet er das automatisch an den Lead. Untereinander schreiben sich Teammates über den Namen an, den der Lead beim Spawnen vergibt. Tipp, sag dem Lead im Prompt wie er die Teammates nennen soll, dann kannst Du sie in späteren Prompts gezielt ansprechen statt zu raten.

9. Quality-Gates mit Team-Hooks erzwingen

Agent Teams bringen eigene Hook-Events mit, mit denen Du Regeln durchsetzt wenn Teammates Arbeit abschließen oder Tasks entstehen. TeammateIdle feuert kurz bevor ein Teammate idle geht, mit Exit-Code 2 schickst Du Feedback und hältst ihn am Arbeiten. TaskCreated feuert beim Anlegen einer Task, Exit-Code 2 verhindert die Erstellung und gibt Feedback. TaskCompleted feuert beim Abschließen, Exit-Code 2 blockt das Abschließen.

Praktisch heißt das, Du kannst zum Beispiel verhindern dass ein Teammate idle geht solange die Tests rot sind, oder dass eine Task als fertig markiert wird ohne dass ein Lint-Check durchlief. Wer Hooks noch nicht aufgesetzt hat, fängt am besten mit dem Hooks-Debugging-Playbook an, das Exit-Code-2-Pattern ist dort schon erklärt und gilt hier genauso.

10. Aufräumen und Rollen wiederverwenden

Zwei Sachen zum Schluss. Erstens das Aufräumen, wenn Du fertig bist sag dem Lead er soll cleanup machen. Das entfernt die geteilten Team-Ressourcen. Achtung, der Cleanup scheitert wenn noch aktive Teammates laufen, also vorher die einzelnen Teammates herunterfahren ("bitte den Researcher-Teammate herunterfahren"). Team-Config liegt unter ~/.claude/teams/{team-name}/config.json, die Task-Liste unter ~/.claude/tasks/{team-name}/. Editier die Config nicht von Hand, Claude überschreibt sie beim nächsten State-Update.

Zweitens, wiederverwendbare Rollen. Du kannst beim Spawnen eine bestehende Subagent-Definition referenzieren ("spawn einen Teammate mit dem security-reviewer Agent-Type"). Dann erbt der Teammate dessen Tools-Allowlist und Modell, und die Definition wird als Zusatz-Instruktion an seinen System-Prompt gehängt. So definierst Du eine Rolle einmal und nutzt sie sowohl als delegierten Subagent als auch als Team-Teammate. Die Koordinations-Tools wie SendMessage und das Task-Management bleiben dem Teammate immer erhalten, auch wenn die Definition andere Tools einschränkt.

Was als nächstes

Wenn Du jetzt unsicher bist ob Du für eine konkrete Aufgabe ein Team, einen Subagent oder doch nur ein Skill brauchst, lies Sub-Agent oder Skill oder MCP-Tool, das gibt Dir die Entscheidungsmatrix. Und wenn Du tiefer in die klassische Subagent-Orchestrierung willst, also Worker die zurückmelden statt miteinander zu reden, ist Subagent-Team strukturieren der nächste Schritt. Inhaltlich passt das Ganze in Level 5, schau Dir parallel die Lesson Research, Critic, Analyst an, das Adversarial-Pattern aus Schritt 1 ist dort als Konzept beschrieben.

Source

Alle Spezifika in diesem Playbook stammen aus der offiziellen Claude-Code-Dokumentation, Stand 8. Juni 2026: https://code.claude.com/docs/en/agent-teams