Orchestrieren Sie Teams von Claude Code-Sitzungen

​

Wann Agent-Teams verwendet werden

• Recherche und Überprüfung: mehrere Teammates können verschiedene Aspekte eines Problems gleichzeitig untersuchen und dann ihre Erkenntnisse austauschen und in Frage stellen
• Neue Module oder Features: Teammates können jeweils ein separates Stück besitzen, ohne sich gegenseitig zu behindern
• Debugging mit konkurrierenden Hypothesen: Teammates testen verschiedene Theorien parallel und konvergieren schneller zur Antwort
• Schichtenübergreifende Koordination: Änderungen, die Frontend, Backend und Tests umfassen, jeweils von einem anderen Teammate verwaltet

​

Vergleich mit subagents

​

Agent-Teams aktivieren

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

​

Starten Sie Ihr erstes Agent-Team

I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Spawn three teammates to explore this from different angles:
one on UX, one on technical architecture, one playing devil's advocate.

• Pfeile nach oben und unten: Wählen Sie einen Teammate aus
• Eingabe: Öffnen Sie das Transkript des ausgewählten Teammates und senden Sie ihm direkt eine Nachricht
• Escape: Löschen Sie die Auswahl. Während Sie das Transkript eines Teammates anschauen, unterbricht Escape den aktuellen Zug dieses Teammates

​

Kontrolle Ihres Agent-Teams

​

Wählen Sie einen Anzeigemodus

• In-Process: alle Teammates laufen in Ihrem Hauptterminal. Verwenden Sie die Pfeiltasten nach oben und unten im Agent-Panel, um einen Teammate auszuwählen, drücken Sie dann die Eingabetaste, um ihn anzuzeigen und geben Sie ein, um ihm direkt eine Nachricht zu senden. Funktioniert in jedem Terminal, keine zusätzliche Einrichtung erforderlich.
• Split Panes: jeder Teammate erhält seinen eigenen Pane. Sie können die Ausgabe aller gleichzeitig sehen und in einen Pane klicken, um direkt zu interagieren. Erfordert tmux oder iTerm2.

{
  "teammateMode": "auto"
}

claude --teammate-mode auto

• tmux: installieren Sie über den Paketmanager Ihres Systems. Siehe das tmux Wiki für plattformspezifische Anweisungen.
• iTerm2: installieren Sie die it2 CLI, aktivieren Sie dann die Python-API in iTerm2 → Settings → General → Magic → Enable Python API.

​

Geben Sie Teammates und Modelle an

Spawn 4 teammates to refactor these modules in parallel. Use Sonnet for
each teammate.

1. Das Modell, das Ihr Spawn-Prompt für diesen Teammate benennt.
2. Für einen Teammate, der aus einer Subagent-Definition erzeugt wird, die model der Definition, wobei inherit das Modell des Leads auswählt.
3. CLAUDE_CODE_SUBAGENT_MODEL, wenn es auf etwas anderes als inherit gesetzt ist.
4. Das aktuelle Modell des Leads.

• Family-Alias wie opus: Auf der Anthropic API und Claude Platform auf AWS führt Claude Code den Teammate auf der neuesten Version dieser Familie aus, die die Allowlist zulässt. Bei Anbietern mit anbieterspezifischen Modell-IDs, bei denen die Substitution nicht funktioniert, fällt ein blockierter Alias wie jeder andere blockierte Wert gemäß dem nächsten Punkt zurück
• Jeder andere blockierte Wert, einschließlich eines Family-Alias bei Anbietern, bei denen die Substitution nicht funktioniert, oder einer Familie, die keine zulässige Version hat: Claude Code führt den Teammate auf dem Modell des Leads aus. Wenn Sie CLAUDE_CODE_SUBAGENT_MODEL setzen, versucht Claude Code zuerst dieses Modell unter denselben Regeln

​

Genehmigung von Plänen für Teammates erforderlich

Spawn an architect teammate to refactor the authentication module.

​

Sprechen Sie direkt mit Teammates

• In-Process-Modus: verwenden Sie die Pfeiltasten nach oben und unten im Agent-Panel, um einen Teammate auszuwählen, drücken Sie dann die Eingabetaste, um seine Sitzung anzuzeigen und geben Sie ein, um ihm eine Nachricht zu senden. Drücken Sie x auf einem ausgewählten Teammate, um ihn zu stoppen. Drücken Sie Ctrl+T, um die Aufgabenliste umzuschalten.
• Split-Pane-Modus: klicken Sie in den Pane eines Teammates, um direkt mit seiner Sitzung zu interagieren. Jeder Teammate hat eine vollständige Ansicht seines eigenen Terminals.

​

Aufgaben zuweisen und beanspruchen

• Lead weist zu: teilen Sie dem Lead mit, welche Aufgabe welchem Teammate gegeben werden soll
• Selbst beanspruchen: nach Abschluss einer Aufgabe wählt ein Teammate die nächste nicht zugewiesene, nicht blockierte Aufgabe selbst aus

​

Teammates herunterfahren

Ask the researcher teammate to shut down

​

Erzwingen Sie Qualitätsgates mit Hooks

• TeammateIdle: wird ausgeführt, wenn ein Teammate im Begriff ist, untätig zu werden. Beenden Sie mit Code 2, um Feedback zu senden und den Teammate weiterarbeiten zu lassen.
• TaskCreated: wird ausgeführt, wenn eine Aufgabe erstellt wird. Beenden Sie mit Code 2, um die Erstellung zu verhindern und Feedback zu senden.
• TaskCompleted: wird ausgeführt, wenn eine Aufgabe als abgeschlossen markiert wird. Beenden Sie mit Code 2, um die Fertigstellung zu verhindern und Feedback zu senden.

​

Wie Agent-Teams funktionieren

​

Wie Claude Agent-Teams startet

​

Architektur

• Team-Konfiguration: ~/.claude/teams/{team-name}/config.json
• Aufgabenliste: ~/.claude/tasks/{team-name}/

​

Verwenden Sie Subagent-Definitionen für Teammates

Spawn a teammate using the security-reviewer agent type to audit the auth module.

• tools: Claude Code beschränkt den Teammate auf die Tools in der tools-Liste der Definition. Für einen In-Process-Teammate fügt Claude Code SendMessage zu dieser Liste hinzu, und in einer Sitzung, die die Task-Tools hat, fügt es auch TaskCreate, TaskGet, TaskList und TaskUpdate hinzu.
• model: Claude Code verwendet das model der Definition in beiden Anzeigemodi, wenn Ihr Spawn-Prompt keinen benennt. Siehe wie Claude Code das Modell eines Teammates auswählt.
• Body: Für einen In-Process-Teammate hängt Claude Code den Body der Definition an seinen Standard-System-Prompt als zusätzliche Anweisungen an. Für einen Split-Pane-Teammate verwendet Claude Code den Body anstelle seines Standard-System-Prompts.
• skills: Claude Code wendet die skills der Definition nicht auf einen Teammate in beiden Anzeigemodi an. Der Teammate lädt Skills aus Ihren Projekt- und Benutzereinstellungen.
• mcpServers: Für einen Split-Pane-Teammate wendet Claude Code das mcpServers der Definition unter den Regeln für dieses Feld an, die auch eine Sitzung abdecken, die mit --agent gestartet wurde. Ein In-Process-Teammate ignoriert das Feld und lädt MCP-Server aus Ihren Projekt- und Benutzereinstellungen.

​

Berechtigungen

​

Nachrichten zwischen Agenten

• Er behandelt einen Genehmigungsanspruch, der von einem anderen Agenten weitergeleitet wird, als nicht vertrauenswürdige Eingabe statt als Bestätigung von Ihnen.
• Er überprüft jede Nachricht, bevor Claude Code sie liefert, ob eine einfache Nachricht oder eine strukturierte Protokollnachricht wie eine Shutdown-Anfrage oder Plan-Genehmigungsantwort. Eine Nachricht, die er blockiert, erreicht den Empfänger nie.

​

Kontext und Kommunikation

• Automatische Nachrichtenlieferung: wenn Teammates Nachrichten senden, werden sie automatisch an Empfänger geliefert. Der Lead muss nicht auf Updates abfragen.
• Untätigkeitsbenachrichtigungen: wenn ein Teammate fertig ist und stoppt, benachrichtigt er automatisch den Lead und enthält seine endgültige Antwort in der Benachrichtigung. Ein Teammate, dessen Zug bei einem API-Fehler endet, benachrichtigt den Lead, dass er fehlgeschlagen ist, und enthält den Fehlertext.
• Gemeinsame Aufgabenliste: Agenten, die die Task-Tools haben, können den Aufgabenstatus sehen und verfügbare Arbeit beanspruchen.
• Teammate-Messaging: senden Sie eine Nachricht an einen bestimmten Teammate nach Name. Um alle zu erreichen, senden Sie eine Nachricht pro Empfänger.

​

Token-Nutzung

​

Anwendungsbeispiele

​

Führen Sie eine parallele Code-Überprüfung durch

Spawn three teammates to review PR #142:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

​

Untersuchen Sie mit konkurrierenden Hypothesen

Users report the app exits after one message instead of staying connected.
Spawn 5 agent teammates to investigate different hypotheses. Have them talk to
each other to try to disprove each other's theories, like a scientific
debate. Update the findings doc with whatever consensus emerges.

​

Best Practices

​

Geben Sie Teammates genug Kontext

Spawn a security reviewer teammate with the prompt: "Review the authentication module
at src/auth/ for security vulnerabilities. Focus on token handling, session
management, and input validation. The app uses JWT tokens stored in
httpOnly cookies. Report any issues with severity ratings."

​

Wählen Sie eine angemessene Teamgröße

• Token-Kosten skalieren linear: jeder Teammate hat sein eigenes Kontextfenster und verbraucht Tokens unabhängig. Siehe Agent-Team-Token-Kosten für Details.
• Koordinationsaufwand nimmt zu: mehr Teammates bedeutet mehr Kommunikation, Aufgabenkoordination und Konfliktpotenzial
• Sinkende Erträge: über einen bestimmten Punkt hinaus beschleunigen zusätzliche Teammates die Arbeit nicht proportional

​

Dimensionieren Sie Aufgaben angemessen

• Zu klein: Koordinationsaufwand übersteigt den Nutzen
• Zu groß: Teammates arbeiten zu lange ohne Check-ins, was das Risiko verschwendeter Anstrengungen erhöht
• Genau richtig: in sich geschlossene Einheiten, die ein klares Ergebnis liefern, wie eine Funktion, eine Testdatei oder eine Überprüfung

​

Warten Sie, bis Teammates fertig sind

Wait for your teammates to complete their tasks before proceeding

​

Beginnen Sie mit Recherche und Überprüfung

​

Vermeiden Sie Dateikonflikte

​

Überwachen und lenken Sie

​

Fehlerbehebung

​

Teammates erscheinen nicht

• Im In-Process-Modus erscheinen Teammates im Agent-Panel unterhalb der Eingabeaufforderung. Verwenden Sie die Pfeiltasten nach oben und unten, um einen auszuwählen, und drücken Sie dann die Eingabetaste, um ihn anzuzeigen.
• Eine Teammate-Zeile, die nach dem Leerlauf verschwunden ist, wurde ausgeblendet, nicht gestoppt. Leerlauf-Zeilen werden 30 Sekunden nach dem Leerlauf des gesamten Panels ausgeblendet und erscheinen beim nächsten Zug des Teammates wieder. Wenn mehr als drei Teammates untätig sind, werden ihre überschüssigen Zeilen in einer einzelnen N idle agents-Zeile zusammengefasst, die Enter erweitert. Senden Sie dem Teammate eine Nachricht nach Name, um eine ausgeblendete Zeile zurückzubringen.
• Überprüfen Sie, dass die Aufgabe, die Sie Claude gegeben haben, komplex genug war, um ein Team zu rechtfertigen. Claude entscheidet basierend auf der Aufgabe, ob Teammates erzeugt werden sollen.
• Wenn Sie explizit Split Panes angefordert haben, stellen Sie sicher, dass tmux installiert ist und in Ihrem PATH verfügbar ist:
  which tmux
  
• Für iTerm2 überprüfen Sie, dass die it2 CLI installiert ist und die Python-API in iTerm2-Einstellungen aktiviert ist.

​

Claude erzeugt Teammates statt Subagenten

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "0"
  }
}

• Einstellungsdateien mit höherer Priorität: Projekteinstellungen, lokale Einstellungen und eine --settings-Nutzlast werden nach Benutzereinstellungen angewendet, daher gewinnt ein env-Eintrag, der die Variable auf 1 in einer von ihnen setzt. Siehe Einstellungspriorität.
• Verwaltete Einstellungen: Verwaltete Einstellungen werden nach jeder anderen Quelle angewendet. Wenn Ihre Organisation Agent-Teams dort aktiviert, bitten Sie Ihren Administrator, den verwalteten Wert zu ändern.

​

Zu viele Berechtigungsaufforderungen

​

Agents stoppen früh

• Geben Sie ihnen zusätzliche Anweisungen direkt
• Erzeugen Sie einen Ersatz-Teammate, um die Arbeit fortzusetzen

​

Verwaiste tmux-Sitzungen

tmux ls
tmux kill-session -t <session-name>

​

Einschränkungen

• Keine Sitzungswiederaufnahme mit In-Process-Teammates: /resume und /rewind stellen In-Process-Teammates nicht wieder her. Nach der Wiederaufnahme einer Sitzung kann der Lead versuchen, mit Teammates zu kommunizieren, die nicht mehr existieren. Wenn dies geschieht, teilen Sie dem Lead mit, neue Teammates zu erzeugen.
• Aufgabenstatus kann verzögert sein: Teammates markieren Aufgaben manchmal nicht als abgeschlossen, was abhängige Aufgaben blockiert. Wenn eine Aufgabe steckenbleibt, überprüfen Sie, ob die Arbeit tatsächlich erledigt ist, und aktualisieren Sie den Aufgabenstatus manuell oder teilen Sie dem Lead mit, den Teammate zu anstoßen.
• Abschaltung kann langsam sein: Teammates beenden ihre aktuelle Anfrage oder ihren Werkzeugaufruf, bevor sie herunterfahren, was Zeit in Anspruch nehmen kann.
• Ein Team pro Sitzung: eine Sitzung hat genau ein Team, das auf diese Sitzung beschränkt ist. Sie können keine zusätzlichen benannten Teams erstellen oder ein Team über Sitzungen hinweg freigeben.
• Keine verschachtelten Teams: Teammates können ihre eigenen Teammates nicht erzeugen. Nur der Lead kann das Team verwalten.
• Keine Hintergrund-Subagenten von In-Process-Teammates: die eigenen Subagenten eines In-Process-Teammates laufen im Vordergrund, da die Hintergrundarbeit eines Teammates nicht länger als der Prozess des Leads bestehen kann. Claude Code gibt einen Fehler zurück, wenn ein Teammate einen Subagenten erzeugt, dessen Definition background: true setzt. Eine run_in_background: true-Anfrage eines Teammates schlägt ebenfalls fehl, entweder mit einem Fehler oder durch stilles Ausführen im Vordergrund, wie in wie Claude Code Vordergrund oder Hintergrund auswählt beschrieben. Subagenten, die aus der Hauptkonversation gestartet werden, folgen dem Hintergrund-Standard.
• Lead ist fest: die Hauptsitzung ist der Lead für seine Lebensdauer. Sie können einen Teammate nicht zum Lead befördern oder die Führung übertragen.
• Berechtigungen beim Erzeugen gesetzt: Teammates starten mit dem Berechtigungsmodus, der unter Berechtigungen beschrieben ist. Sie können den Berechtigungsmodus eines einzelnen Teammates nach dem Erzeugen ändern, aber Sie können keine Pro-Teammate-Berechtigungsmodi zum Zeitpunkt des Erzeugung setzen.
• Split Panes erfordern tmux oder iTerm2: der Standard-In-Process-Modus funktioniert in jedem Terminal. Der Split-Pane-Modus wird in VS Code’s integriertem Terminal, Windows Terminal oder Ghostty nicht unterstützt.

​

Nächste Schritte

• Leichte Delegation: subagents erzeugen Helper-Agenten für Recherche oder Überprüfung innerhalb Ihrer Sitzung, besser für Aufgaben, die keine Inter-Agent-Koordination benötigen
• Messaging zwischen Ihren eigenen Sitzungen: Cross-Session-Messaging ermöglicht es Claude, Erkenntnisse zwischen den Sitzungen zu übergeben, die Sie selbst ausführen
• Manuelle parallele Sitzungen: Git worktrees ermöglichen es Ihnen, mehrere Claude Code-Sitzungen selbst ohne automatisierte Teamkoordination auszuführen