Mehrere Claude-Code-Agenten parallel ausführen: So geht's

TL;DR: Wenn Sie mehrere Claude-Code-Agenten parallel ausführen möchten, weisen Sie jeder Session ein eigenes Git-Worktree zu (claude -w <name> erledigt das mit einem einzigen Flag), verschieben Sie Sessions, die Sie gerade nicht im Blick haben, mit claude --bg in den Hintergrund und legen Sie die Merge-Reihenfolge fest, bevor die Agenten fertig sind – denn auch isolierte Branches kollidieren beim Mergen. Wenn sich zwei Sessions einen Checkout teilen, landet der unfertige Code des einen Agenten schnell im Commit des anderen. Dieser Leitfaden richtet sich an Entwickler, die Claude Code bereits nutzen und zwei bis fünf Sessions gleichzeitig laufen lassen möchten.

Alles beginnt mit einem zweiten Terminal. Im ersten refaktoriert Claude Code gerade das Auth-Modul; also öffnen Sie ein weiteres Terminal und beauftragen eine neue Session damit, den instabilen Datumstest zu reparieren. Dann folgt ein drittes für die Dokumentation. Zwanzig Minuten später schreiben drei Sessions in dasselbe Arbeitsverzeichnis, git status listet Dateien auf, die Sie gar nicht beauftragt haben, und niemand weiß mehr, welche Session eigentlich config.ts geändert hat.

Mehrere Claude-Code-Agenten zu starten ist simpel: Öffnen Sie einfach weitere Terminals. Doch damit sie laufen, ohne sich gegenseitig die Arbeit zu ruinieren, müssen Sie drei Entscheidungen treffen: wo die Dateien der einzelnen Sessions liegen, wie Sie Sessions im Blick behalten, die Sie nicht aktiv beobachten, und in welcher Reihenfolge deren Branches zusammengeführt werden. Dieser Beitrag behandelt alle drei Punkte anhand der integrierten Befehle von Claude Code sowie zweier Fehlerszenarien, die wir auf einem Test-Repository nachgestellt haben. Falls Worktrees neu für Sie sind, lesen Sie zunächst unseren Leitfaden zu Git-Worktrees mit KI-Coding-Agenten oder die Git-Worktree-Referenz.

Warum mehrere Claude-Code-Agenten einen gemeinsamen Checkout lahmlegen

Mehrere Claude-Code-Agenten parallel auszuführen bedeutet, dass zwei oder mehr Sessions gleichzeitig am selben Repository arbeiten – jeweils mit einer eigenen Aufgabe und einem eigenen Kontextfenster. Die Sessions wissen nichts voneinander. Jede liest Dateien, editiert sie, führt Tests aus und committet, als wäre sie völlig allein im Projekt.

Ein Checkout besitzt jedoch nur ein Arbeitsverzeichnis, einen Index und einen HEAD – weshalb diese „Als-wäre-ich-allein“-Annahme schnell scheitert. Wir haben das gängigste Szenario auf einem simplen Python-Repo nachgestellt, wobei zwei Shell-Skripte die Agenten simulierten. Agent B hat eine halb fertige truncate()-Funktion in textutils.py gespeichert. Agent A schließt seine Aufgabe in einer anderen Datei ab und committet so, wie es viele Prompts vorgeben: mit git add -A && git commit:

$ git show --stat --format='%an: %s' HEAD
agent-a: add slugify
 slug.py      | 2 ++
 textutils.py | 4 ++++
 2 files changed, 6 insertions(+)

$ python3 -m pytest -q
1 error in 0.09s

Der Commit von Agent A enthält nun den unfertigen Code von Agent B, und die Test-Suite bricht schon beim Import ab. Dabei wurde nichts überschrieben: Weil der Index geteilt wurde, hat der Commit von Agent A die unfertige Arbeit von Agent B einfach mitgenommen – und in der Git-Historie sieht es nun so aus, als hätte Agent A fehlerhaften Code geschrieben. Was passiert, wenn zwei Agenten tatsächlich dieselbe Datei bearbeiten, beleuchten wir im Artikel Was passiert, wenn zwei Coding-Agenten dieselbe Datei bearbeiten.

Mehrere Claude-Code-Agenten mit jeweils eigenem Worktree ausführen

Die Lösung lautet: ein separates Arbeitsverzeichnis pro Session. Claude Code liefert dafür direkt ein passendes Flag mit:

# interactive sessions, one task each, each in its own worktree
claude -w auth-refactor
claude -w flaky-date-test --tmux   # opens the session in its own tmux or iTerm2 pane

# fire-and-forget work: starts in the background and prints an id
claude --bg "update the README examples for the new config format"

Laut der Dokumentation zu Worktrees erstellt claude -w <name> ein Worktree unter .claude/worktrees/<name>/ auf einem neuen Branch namens worktree-<name>. Ein zweites Terminal mit einem anderen Namen erhält damit eine vollständig isolierte Session. In unseren Tests stufte Git das neue Worktree direkt als locked ein, was verhindert, dass git worktree prune es während einer laufenden Session versehentlich löscht. Hintergrund-Sessions, die mit --bg oder /bg gestartet werden, wechseln laut der Agent-View-Dokumentation automatisch in ihr eigenes Worktree unter .claude/worktrees/, bevor sie Änderungen vornehmen.

Drei Setup-Details ersparen Ihnen jede Menge Ärger:

1. Den Ordner ignorieren: Worktrees liegen innerhalb des Repositories. Daher zeigt git status im Haupt-Checkout .claude/ so lange als untracked an, bis Sie .claude/worktrees/ zu Ihrer .gitignore hinzufügen – was auch in der Dokumentation ausdrücklich empfohlen wird.
2. Mit einem frischen Checkout rechnen: Ein neues Worktree enthält weder node_modules noch virtuelle Umgebungen oder eine .env-Datei. Führen Sie ignorierte Dateien, die kopiert werden müssen (wie etwa .env), in einer Datei namens .worktreeinclude auf und planen Sie für jedes Worktree einen Installationsschritt ein.
3. Headless-Runs manuell aufräumen: Interaktive Sessions bieten beim Beenden an, ihr Worktree zu löschen. Läufe, die mit claude -p gestartet wurden, räumen sich nie selbst auf – entfernen Sie diese also manuell über git worktree unlock und anschließend git worktree remove.

Hintergrund-Sessions werden über die Shell verwaltet. Die folgenden Befehlsbeschreibungen stammen aus claude --help der Version 2.1.283:

--bg lässt sich nicht mit -p kombinieren. Für eine skriptbasierte Parallelisierung zeigt Anthopics Leitfaden für die Arbeit mit Claude Code eine Shell-Schleife über claude -p mit --allowedTools und --permission-mode dontAsk. Kombinieren Sie dies mit -w, damit jeder Durchlauf sein eigenes Verzeichnis erhält.

Auch isolierte Claude-Code-Agenten kollidieren beim Mergen

Worktrees verhindern, dass sich Sessions während der Arbeit gegenseitig in die Quere kommen. Kompatibel wird ihr Code dadurch aber nicht automatisch. Wir haben auf zwei Worktree-Branches ähnliche Änderungen vorgenommen – beide fügten jeweils eine Funktion am Ende von textutils.py ein – und anschließend beide zusammengeführt:

$ git merge agent/slugify
Fast-forward
$ git merge agent/truncate
Auto-merging textutils.py
CONFLICT (content): Merge conflict in textutils.py
Automatic merge failed; fix conflicts and then commit the result.

Keiner der Agenten hat einen Fehler gemacht: Beide haben Code an derselben Stelle eingefügt, und Git kann nicht selbst entscheiden, welche Reihenfolge gilt. In einer echten Codebasis mit vier oder fünf Sessions ist das der Normalfall für jede zentrale Datei: Routing-Tabellen, __init__.py-Exporte, Changelogs, Lockfiles. Der Unterschied zum geteilten Checkout liegt darin, dass die Kollision nun sofort auffällt, eindeutig sichtbar ist und sich klar zuordnen lässt. Drei Gewohnheiten halten den Aufwand gering:

1. Aufgaben nach Dateien aufteilen, nicht nach Features: Zwei Tasks, die beide Änderungen am Router erfordern, gehören in eine einzige Aufgabe – oder müssen nacheinander ausgeführt werden.
2. In fester Reihenfolge mergen und den Rest rebasen: Mergen Sie den ersten Branch und fordern Sie die nächste Session auf, ein Rebase auf main durchzuführen und die Tests erneut laufen zu lassen, bevor Sie das Review starten. Die Session, die den Code geschrieben hat, besitzt bereits den nötigen Kontext, um ihren Konflikt selbst aufzulösen.
3. Worktrees nach ihren Aufgaben benennen: claude -w fix-date-test ist wesentlich aussagekräftiger als claude -w agent2, wenn Sie eine Stunde später in die Ausgabe von git worktree list schauen.

Der eigentliche Engpass ist meistens nicht Git, sondern Sie selbst beim Prüfen von fünf verschiedenen Diffs. In unserem Beitrag darüber, warum menschliche Reviews das Nadelöhr bei parallelen Agenten sind, erläutern wir, wie Sie diese Queue richtig dimensionieren.

Subagents, Agent Teams oder separate Sessions für mehrere Claude-Code-Agenten

Claude Code bietet mittlerweile mehrere Möglichkeiten, Aufgaben parallel auszuführen; die Übersicht zu parallelen Agenten stellt sie gegenüber. Sie sind jedoch nicht beliebig austauschbar. Der entscheidende Faktor ist die Dateiisolation:

Verwenden Sie für unabhängige Aufgaben separate Sessions mit Worktrees. Setzen Sie auf Agent Teams, wenn Teilaufgaben voneinander abhängen und Abstimmung nötig ist – und weisen Sie jedem Teammitglied unterschiedliche Dateien zu. Die Dokumentation zu Agent Teams formuliert das unmissverständlich: „Bearbeiten zwei Teammitglieder dieselbe Datei, kommt es zu Überschreibungen.“ Für welches Modell Sie sich auch entscheiden: Das Nutzungskontingent wird gemeinsam verbraucht. In der Agent-View-Dokumentation heißt es dazu treffend: „Wer zehn Agenten parallel laufen lässt, verbraucht sein Kontingent rund zehnmal so schnell wie mit einem einzelnen.“

Wie Sharkly ins Spiel kommt, wenn Sie mehrere Claude-Code-Agenten nutzen

Wenn Sie zwei oder drei Sessions auf Ihrem eigenen Laptop betreiben und jedes Diff persönlich reviewen, genügen die oben beschriebenen Befehle vollkommen – Sharkly brauchen Sie dann vermutlich nicht. Die Ausgangslage ändert sich jedoch, sobald mehrere Personen involviert sind oder die Frage „In welcher Session lag noch gleich der Fix für den Datumstest?“ länger dauert als die eigentliche Reparatur.

Sie nutzen bereits Coding-Agenten. Sharkly formt daraus ein eingespieltes Team. Jede Aufgabe wird zu einem Task. Sie weisen sie einem Agenten zu, der auf der Claude Code Runtime auf einem Ihrer Computer läuft – und das Setzen des Assignees startet den Lauf. Mit dem standardmäßigen Arbeitsverzeichnis Create temporary directory erhält jeder Task ein eigenes Verzeichnis, und repo-gebundene Läufe bekommen ein isoliertes Git-Worktree: exakt dieselbe Isolation wie bei claude -w, aber ohne dass jemand Worktrees manuell benennen muss. Muss ein Agent eine bereits vorhandene Umgebung auf einem lokalen Computer wiederverwenden, liefert Run in isolated worktrees das Ergebnis jedes Tasks auf einem separaten agent/<agent>/<task>-Branch ab. Über Max concurrency (assigned tasks) lässt sich direkt am Agenten festlegen, wie viele Läufe parallel stattfinden dürfen – genau das Review-Limit von oben, transparent für das gesamte Team definiert.

Fortschritt, Ausführungsverlauf und Ergebnisse fließen direkt in den jeweiligen Task zurück; alles, was menschliche Aufmerksamkeit erfordert, landet in der Inbox. Nichts wird ungeprüft gemergt: Ein Mensch prüft die Änderungen im Worktree, übernimmt, mergt oder verwirft sie und setzt den Task auf „Done“. Die Ausführungen werden weiterhin über Ihren eigenen Claude-Code-Plan abgerechnet, da Sharkly keine Tokens verkauft. Die Funktionsseite zu Agents zeigt die Einrichtung, und unser Artikel Wie Sharkly Agenten parallel ausführt erklärt die technische Umsetzung.

Wenn drei geöffnete Terminals nicht mehr reichen und Sie die Ergebnisse aller Claude-Code-Sessions an einem zentralen Ort bündeln wollen, den Reviewer gezielt abarbeiten können – genau für dieses Problem wurde Sharkly entwickelt.

FAQ

Wie viele Claude-Code-Agenten kann ich gleichzeitig ausführen? Die Dokumentation setzt für separate Sessions kein festes Limit. Bei Subagents liegt der Standardwert bei maximal 20 gleichzeitig aktiven Instanzen, und für Agent Teams wird ein Start mit 3 bis 5 Teammitgliedern empfohlen. Die tatsächlichen Grenzen setzen Ihr Nutzungskontingent, die CPU- und RAM-Ressourcen Ihres Laptops sowie die Frage, wie viele Ergebnisse Sie pro Tag reviewen können. Die Berechnung der Review-Kapazität lohnt sich definitiv, bevor Sie eine sechste Session starten.

Teilen sich parallele Claude-Code-Sessions meine Nutzungslimits? Ja. Bei Pro und Max werden die Nutzungslimits zwischen Claude und Claude Code geteilt, mit einem Fünf-Stunden-Fenster und einem wöchentlichen Kontingent; jede parallele Session greift auf denselben Pool zu. Ist ANTHROPIC_API_KEY gesetzt, rechnet Claude Code stattdessen über die API ab.

Kopiert claude --worktree meine .env-Datei und Abhängigkeiten mit? Nein. Jedes Worktree ist ein frischer Checkout. Fügen Sie benötigte, von Git ignorierte Dateien wie .env in .worktreeinclude ein und führen Sie die Installationsschritte für Abhängigkeiten in jedem Worktree separat aus.

Kann ich Claude Code und Codex parallel im selben Repository ausführen? Ja – es gelten dieselben Regeln: ein separates Worktree pro Session und eine klare Merge-Reihenfolge. Unser Leitfaden zur gemeinsamen Nutzung von Claude Code und Codex in einer Codebasis behandelt das Routing im Detail.