Claude Code: Limit von 30 Minuten für Hintergrundbefehle

Claude Code beendet einen Hintergrundbefehl nach 30 Minuten, wenn er unbeaufsichtigt ausgeführt wird: bei einem Start mit dem Flag -p, einer Agent-SDK-Anwendung, einem CI-Job oder einer Cloud-Sitzung. Wenn Claude selbst eine Zeit für den Befehl festlegt, läuft er höchstens 2 Stunden. Im normalen Terminal, in der Desktop-App und in VS Code gibt es seit Version 2.1.288 kein Limit mehr.

Früher saß ich den ganzen Tag vor dem Bildschirm: dem Agenten einen Schritt geben, nachsehen, eine Korrektur vornehmen und ihn bitten weiterzumachen. Phase um Phase. Der Rechner schreibt vielleicht den Code, aber ich war derjenige, der ihn steuerte. Jetzt schreibe ich einen Plan, teile ihn in Phasen auf, überlasse die Umsetzung über Nacht den Subagents und gehe. In 8 Stunden ohne mich arbeitet Claude den Plan ab: recherchiert, baut und verfeinert. Am Morgen verbringe ich mehr Zeit damit, die Arbeit abzunehmen, als sie neu zu machen.

Wenn ein Lauf über Nacht aber -p verwendet, auf einem Server nach Zeitplan, in CI oder in der Cloud läuft, halten ein Entwicklungsserver und ein Build im Hintergrund 30 Minuten durch. Dann beendet Claude Code sie, und die Arbeit über Nacht kommt auf halber Strecke ins Stocken. Ich erkläre, wen das Limit betrifft, wie du es erhöhst und was zu tun ist, wenn ein Befehl bereits gestoppt wurde. Los geht's.

Hilfe zur Nutzung des Dienstes findest du in der Ailoot-Dokumentation.

Welche Claude-Code-Ausführungen betrifft das Hintergrundlimit?#

Ein Hintergrundbefehl ist etwas, das Claude startet und weiterlaufen lässt, während es mit etwas anderem beschäftigt ist. Zum Beispiel ein Entwicklungsserver, der mit npm run dev gestartet wurde, oder ein Build, der Dateien auf Änderungen überwacht.

Die Claude-Code-Dokumentation sagt:

Anders gesagt: Das Limit gilt, wenn du nicht dabei bist: bei einem Lauf mit -p, einer Agent-SDK-Anwendung, einem CI-Job oder einer Cloud-Sitzung. Im Terminal, in der Desktop-App oder in VS Code gibt es kein Limit, wenn du selbst in der Sitzung arbeitest. Es wurde mit Version 2.1.285 eingeführt und galt vor Version 2.1.288 überall.

So erkennst du, ob das auf dich zutrifft:

• Du hast Claude Code im Terminal oder in VS Code geöffnet, ihm eine Aufgabe gegeben und bist schlafen gegangen. Bei Version 2.1.288 oder neuer gibt es kein Limit. In den Versionen 2.1.285 bis 2.1.287 gilt es auch hier. Wie du auf die neueste Version aktualisierst, habe ich in einem separaten Artikel erklärt.
• Claude Code wird mit claude -p "task" nach Zeitplan, aus deiner eigenen Agent-SDK-Anwendung oder in CI gestartet. Das Limit gilt.
• Die Aufgabe läuft in einer Cloud-Sitzung. Das Limit gilt.

Wenn ich Agenten selbstständig arbeiten lasse, schreibe ich in den Prompt: „Schreibe diese Bedingungen und die Gründe für den Abbruch in den Arbeitsplan. Prüfe, dass der Prozess nicht von einem Fenster abhängt, das ich schließen werde, oder vom Computer selbst.“ Das 30-Minuten-Limit ist einer dieser Gründe.

Wie lange ein Hintergrundbefehl läuft#

Der Countdown beginnt, sobald der Befehl in den Hintergrund wechselt. Es gibt 2 Fälle.

Claude startet den Befehl sofort im Hintergrund. Er erhält 30 Minuten. Wenn Claude beim Start eine Zeit angibt (den Parameter timeout), erhält er diese Zeit, höchstens jedoch 2 Stunden.

Der Befehl wird nicht fertig, während Claude darauf wartet. Bei einem gewöhnlichen Befehl wartet Claude 2 Minuten. Wenn er bis dahin nicht fertig ist, beendet Claude Code ihn nicht, sondern verschiebt ihn in den Hintergrund. Ab diesem Zeitpunkt hat er 30 Minuten.

Wenn die Zeit abgelaufen ist, beendet Claude Code den Befehl und teilt Claude mit:

Background command "<description>" was stopped after reaching its background time limit

Wenn die Arbeit noch nicht abgeschlossen ist, kann Claude den Befehl mit einer längeren Zeit erneut ausführen.

Noch ein Punkt zu -p. Bei dieser Art von Lauf werden Hintergrundbefehle ungefähr 5 Sekunden nach Claudes letzter Antwort beendet. Ein Server, der bei einem nächtlichen Lauf mit -p gestartet wird, läuft nur so lange wie der Lauf selbst. Das 30-Minuten-Limit ist relevant, wenn der Lauf länger dauert: Claude startet zu Beginn einen Server und verbringt eine Stunde damit, Prüfungen daran auszuführen.

So organisierst du Nachtarbeit in Claude Code#

Ich hatte es satt, den Agenten den ganzen Tag zu steuern, und habe das durch einen einzigen Orchestrator-Prompt ersetzt. Ich starte ihn am Abend, und Claude arbeitet die ganze Nacht und durchläuft die Phasen der Reihe nach: schreiben, prüfen, korrigieren und selbstständig committen.

Gruppen von Subagents schreiben den Code, jeder mit eigenen Dateien, damit sie sich nicht in die Quere kommen. Eine andere, frische Gruppe nimmt die Arbeit ab: Code-Review, Sicherheitsprüfungen und Live-Prüfungen. Wenn sie ein Problem findet, wird es sofort behoben und die Prüfungen werden erneut ausgeführt. Der Prompt enthält die Zeile: „Wenn dir der Kontext ausgeht, halte den Stand fest; der nächste Lauf macht weiter.“

Im beschriebenen Beispiel wurden auf diese Weise innerhalb von 3 Tagen 8 von 14 Phasen abgeschlossen.

Es gibt nur 2 Punkte zu beachten. Der Orchestrator denkt nicht für dich: Schreibe zuerst einen ausführlichen Plan mit Phasen und starte dann die Nachtschicht. Außerdem verbraucht er einen großen Teil deines Abonnementkontingents, daher lohnt sich diese Einrichtung für eine kleine Aufgabe kaum. Begrenze immer die Anzahl der Versuche, sonst verbraucht der Agent über Nacht dein gesamtes Abonnementkontingent. Wie du diese Ausgabenlimits festlegst, habe ich in einem separaten Artikel erklärt.

So erhöhst du das Limit#

Option 1: Claude fragen. Claude wählt die Zeit für einen bestimmten Befehl; du legst sie nicht selbst fest. Du kannst aber in die Aufgabe schreiben: „Lass den Entwicklungsserver 2 Stunden im Hintergrund laufen.“ Auf diesem Weg sind höchstens 2 Stunden möglich.

Option 2: Variablen in der Einstellungsdatei. Die Werte werden in Millisekunden angegeben. Du kannst die Limits nicht unter 30 Minuten und 2 Stunden senken, sondern nur erhöhen.

• BASH_DEFAULT_TIMEOUT_MS: Ein Wert über 1800000 (30 Minuten) ändert den Standardwert von 30 Minuten. Das gilt sowohl für Befehle, die Claude ohne Zeitangabe im Hintergrund startet, als auch für Befehle, die nach einer Zeitüberschreitung in den Hintergrund verschoben werden. Wenn du den Wert über 7200000 (2 Stunden) setzt, steigt auch die Obergrenze.
• BASH_MAX_TIMEOUT_MS: Ein Wert über 7200000 erhöht die Obergrenze von 2 Stunden. Der Standardwert von 30 Minuten ändert sich dadurch nicht: Ein Befehl ohne eigene Zeitangabe wird weiterhin nach 30 Minuten beendet.

BASH_DEFAULT_TIMEOUT_MS hat einen Nebeneffekt. Dieselbe Variable legt fest, wie lange Claude auf einen gewöhnlichen Befehl wartet, bevor es ihn in den Hintergrund verschiebt. Stellst du sie auf 1 Stunde ein, wartet Claude 1 Stunde statt 2 Minuten. Über Nacht stört das nicht. Tagsüber wartest du länger auf eine Antwort, wenn Befehle lange dauern.

Wenn du dich nicht mit den Einzelheiten befassen möchtest: Wenn du für gewöhnliche Befehle und die Obergrenze 3 Stunden brauchst, setze BASH_DEFAULT_TIMEOUT_MS auf 10800000. Das reicht; die zweite Variable brauchst du nicht.

Die Einstellungsdatei liegt im .claude-Ordner in deinem Benutzerverzeichnis: ~/.claude/settings.json unter macOS und Linux sowie %USERPROFILE%\.claude\settings.json unter Windows. Wenn die Datei nicht existiert, erstelle sie. Ein Limit von 1 Stunde sieht so aus:

{
  "env": {
    "BASH_DEFAULT_TIMEOUT_MS": "3600000"
  }
}

Wenn die Datei bereits einen env-Block enthält, füge die Zeile dort hinzu. Eine laufende Sitzung übernimmt die neuen Werte, sobald du die Datei speicherst. Das Entfernen einer Variablen wird erst wirksam, wenn du claude das nächste Mal startest.

Die Datei muss sich auf dem Rechner befinden, auf dem der Agent läuft. Damit der Agent über Nacht arbeiten kann, darf der Computer nicht in den Ruhezustand wechseln. Alternativ kannst du Claude Code auf einem Remote-Server ausführen und die Einstellungen dort ablegen.

Wenn der Befehl bereits gestoppt wurde#

Du musst nichts manuell tun. Claude Code teilt Claude mit, warum ein Befehl gestoppt wurde. Frage also zunächst einfach, was passiert ist.

Gehe dann Schritt für Schritt vor:

1. Einmaliger langer Lauf von bis zu 2 Stunden. Bitte Claude, den Befehl mit einer längeren Zeit erneut auszuführen.
2. Befehle benötigen regelmäßig mehr als 30 Minuten. Setze BASH_DEFAULT_TIMEOUT_MS in der Einstellungsdatei auf einen Wert über 1800000, wie im obigen Beispiel. Wenn du mehr als 2 Stunden brauchst, setze dort zusätzlich BASH_MAX_TIMEOUT_MS auf einen Wert über 7200000.
3. Führe den Befehl erneut aus. Die Dokumentation macht keine Zusagen für einen Befehl, der bereits vor der Änderung im Hintergrund lief.
4. Prüfe das Ergebnis des nächsten Laufs. Wenn Claudes Bericht erneut die Formulierung „stopped after reaching its background time limit“ enthält, wurde die Einstellung auf diesen Befehl nicht angewendet.

Subagents und Routinen sorgen dafür, dass der Agent weiterarbeitet, während du abwesend bist.

Wie du einen Agenten die ganze Nacht in einer Schleife laufen lässt, habe ich in einem separaten Artikel erklärt. Und hier erfährst du, wie du Claude Code so konfigurierst, dass es das Projekt nicht über Nacht beschädigt.

Prüfe, an welchem Schritt dein Nachtlauf stoppt, und vergleiche den Grund mit den oben genannten Limits.

Lerne Ailoot kennen.