Claude Code: limiet van 30 minuten voor achtergrondopdrachten

Claude Code stopt een achtergrondopdracht na 30 minuten wanneer die onbeheerd draait: bijvoorbeeld bij een start met de vlag -p, een Agent SDK-applicatie, een CI-taak of een cloudsessie. Als Claude zelf een tijdsduur voor de opdracht instelt, draait die maximaal 2 uur. In de gewone terminal, desktopapp en VS Code geldt sinds versie 2.1.288 geen limiet meer.

Vroeger zat ik de hele dag achter mijn scherm: ik gaf de agent een stap, bekeek het resultaat, stuurde bij en vroeg hem verder te gaan. Fase na fase. De machine schreef misschien de code, maar ik stuurde het proces aan. Nu schrijf ik een plan, verdeel ik het in fases, laat ik subagents de implementatie ’s nachts uitvoeren en ga ik weg. In de 8 uur dat ik er niet ben, werkt Claude het plan af: onderzoeken, bouwen en verfijnen. ’s Ochtends besteed ik meer tijd aan het accepteren van het werk dan aan het opnieuw uitvoeren ervan.

Maar als een nachtelijke run -p gebruikt, volgens een schema op een server draait, in CI plaatsvindt of in de cloud draait, blijft een ontwikkelserver of build op de achtergrond maar 30 minuten actief. Daarna stopt Claude Code die, en loopt het werk van de nacht halverwege vast. Ik leg uit voor wie de limiet geldt, hoe je die verhoogt en wat je doet als een opdracht al is gestopt. Laten we beginnen.

Zie voor hulp bij het gebruik van de dienst de documentatie van Ailoot.

Voor wie geldt de limiet?#

Een achtergrondopdracht is iets wat Claude start en laat draaien terwijl het met iets anders bezig is. Bijvoorbeeld een ontwikkelserver die is gestart met npm run dev, of een build die bestanden op wijzigingen controleert.

In de documentatie van Claude Code staat:

Met andere woorden: de limiet geldt wanneer je er zelf niet bij bent, bijvoorbeeld bij een run met -p, een Agent SDK-applicatie, een CI-taak of een cloudsessie. In de terminal, desktopapp of VS Code geldt geen limiet als je zelf in de sessie werkt. De limiet werd ingevoerd in versie 2.1.285 en gold vóór 2.1.288 overal.

Zo bepaal je of dit voor jou geldt:

• Je hebt Claude Code in de terminal of VS Code geopend, een taak gegeven en bent gaan slapen. Bij versie 2.1.288 of nieuwer geldt er geen limiet. In versies 2.1.285 tot en met 2.1.287 geldt die hier ook. In een apart artikel heb ik uitgelegd hoe je naar de nieuwste versie bijwerkt.
• Claude Code wordt volgens een schema gestart met claude -p "task", vanuit je eigen Agent SDK-applicatie of in CI. De limiet geldt.
• De taak draait in een cloudsessie. De limiet geldt.

Wanneer ik agents zelfstandig laat werken, zet ik deze vraag in de prompt: “Schrijf deze voorwaarden en de redenen om te stoppen in het werkplan. Controleer of het proces niet afhankelijk is van een venster dat ik sluit of van de computer zelf.” De limiet van 30 minuten is een van die redenen.

Hoe lang draait een achtergrondopdracht?#

De klok begint te lopen zodra de opdracht op de achtergrond wordt gezet. Er zijn 2 gevallen.

Claude start de opdracht meteen op de achtergrond. De opdracht krijgt 30 minuten. Als Claude bij het starten een tijdsduur opgeeft (de parameter timeout), krijgt de opdracht die tijd, maar maximaal 2 uur.

De opdracht is nog niet klaar wanneer Claude erop wacht. Claude wacht 2 minuten op een gewone opdracht. Als die dan nog niet klaar is, stopt Claude Code de opdracht niet, maar verplaatst die naar de achtergrond. Vanaf dat moment heeft de opdracht 30 minuten.

Zodra de tijd om is, stopt Claude Code de opdracht en meldt het aan Claude:

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

Als het werk nog niet af is, kan Claude de opdracht opnieuw uitvoeren met een langere tijdsduur.

Nog een punt over -p. Bij dit soort runs worden achtergrondopdrachten ongeveer 5 seconden na het laatste antwoord van Claude beëindigd. Een server die tijdens een nachtelijke run met -p is gestart, blijft dus alleen actief zolang de run zelf duurt. De limiet van 30 minuten is van belang als de run langer duurt: Claude start een server aan het begin en voert er een uur lang controles op uit.

Hoe organiseer je nachtelijk werk in Claude Code?#

Ik was het beu om de agent de hele dag aan te sturen, dus ben ik overgestapt op één prompt voor de orkestrator. Ik start die ’s avonds en Claude doorloopt de fases de hele nacht op volgorde: schrijven, controleren, corrigeren en zelfstandig committen.

Groepen subagents schrijven de code, elk in hun eigen bestanden zodat ze elkaar niet in de weg zitten. Een andere, nieuwe groep neemt het werk over voor de beoordeling: code review, beveiligingscontroles en controles in de praktijk. Als ze een probleem vinden, wordt het meteen opgelost en worden de controles opnieuw uitgevoerd. De prompt bevat de zin: “Als je geen context meer hebt, leg dan de status vast; de volgende run gaat verder.”

In het beschreven voorbeeld werden in 3 dagen op deze manier 8 van de 14 fases afgerond.

Er zijn maar 2 punten om rekening mee te houden. De orkestrator denkt niet voor je: schrijf eerst een gedetailleerd plan met fases en start daarna de nachtelijke dienst. Bovendien kost dit veel van je abonnementslimiet, dus het heeft weinig zin om dit voor een kleine taak in te richten. Beperk altijd het aantal pogingen, anders verbruikt de agent ’s nachts je volledige abonnementslimiet. In een apart artikel heb ik uitgelegd hoe je zulke bestedingslimieten instelt.

Hoe verhoog je de limiet?#

Optie 1: vraag het Claude. Claude kiest de tijd voor een specifieke opdracht; je stelt die niet zelf in. Je kunt wel in de taak zetten: “Laat de ontwikkelserver 2 uur op de achtergrond draaien.” Meer dan 2 uur krijg je op deze manier niet.

Optie 2: variabelen in het instellingenbestand. De waarden zijn in milliseconden. Je kunt de limieten niet verlagen tot minder dan 30 minuten en 2 uur; je kunt ze alleen verhogen.

• BASH_DEFAULT_TIMEOUT_MS instellen op meer dan 1800000 (30 minuten) verandert de standaardlimiet van 30 minuten. Dit geldt zowel voor opdrachten die Claude zonder opgegeven tijd op de achtergrond start als voor opdrachten die na een time-out naar de achtergrond worden verplaatst. Stel je de waarde in op meer dan 7200000 (2 uur), dan wordt ook de bovengrens verhoogd.
• BASH_MAX_TIMEOUT_MS instellen op meer dan 7200000 (2 uur) verhoogt de bovengrens van 2 uur. De standaardlimiet van 30 minuten verandert niet: een opdracht zonder eigen opgegeven tijd stopt nog steeds na 30 minuten.

BASH_DEFAULT_TIMEOUT_MS heeft een neveneffect. Dezelfde variabele bepaalt hoelang Claude op een gewone opdracht wacht voordat die naar de achtergrond wordt verplaatst. Stel je de waarde in op 1 uur, dan wacht Claude 1 uur in plaats van 2 minuten. ’s Nachts zit dat niet in de weg. Overdag moet je langer op antwoord wachten wanneer opdrachten veel tijd kosten.

Wil je je niet in de details verdiepen? Als je zowel voor gewone opdrachten als voor de bovengrens 3 uur nodig hebt, stel je BASH_DEFAULT_TIMEOUT_MS in op 10800000. Dat is genoeg; de tweede variabele is niet nodig.

Het instellingenbestand staat in de map .claude in je thuismap: ~/.claude/settings.json op macOS en Linux, en %USERPROFILE%\.claude\settings.json op Windows. Maak het bestand aan als het niet bestaat. Een limiet van 1 uur ziet er zo uit:

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

Als het bestand al een env-blok bevat, voeg je de regel daaraan toe. Een actieve sessie neemt de nieuwe waarden over zodra je het bestand opslaat. Een variabele verwijderen heeft pas effect wanneer je claude de volgende keer start.

Het bestand moet op de machine staan waarop de agent draait. Om de agent de hele nacht te laten werken, mag de computer niet in de slaapstand gaan. Je kunt Claude Code ook op een externe server draaien en de instellingen daar plaatsen.

Wat als de opdracht al is gestopt?#

Je hoeft zelf niets te doen. Claude Code laat Claude weten waarom een opdracht is gestopt, dus vraag eerst gewoon wat er is gebeurd.

Ga daarna stap voor stap verder:

1. Een eenmalige lange run van maximaal 2 uur. Vraag Claude de opdracht opnieuw uit te voeren met een langere tijdsduur.
2. Opdrachten hebben regelmatig meer dan 30 minuten nodig. Stel in het instellingenbestand BASH_DEFAULT_TIMEOUT_MS in op meer dan 1800000, zoals in het bovenstaande voorbeeld. Als je meer dan 2 uur nodig hebt, stel je daar ook BASH_MAX_TIMEOUT_MS in op meer dan 7200000.
3. Voer de opdracht opnieuw uit. De documentatie garandeert niets over een opdracht die al op de achtergrond draaide voordat je de wijziging aanbracht.
4. Controleer het resultaat van de volgende run. Staat in Claude’s verslag opnieuw de zin “stopped after reaching its background time limit”, dan is de instelling niet op die opdracht toegepast.

Subagents en routines zorgen ervoor dat de agent blijft werken wanneer je weg bent.

In een apart artikel heb ik uitgelegd hoe je een agent de hele nacht in een lus laat draaien. En hier lees je hoe je Claude Code zo configureert dat het je project ’s nachts niet beschadigt.

Controleer bij welke stap je nachtelijke run stopt en vergelijk de reden met de limieten hierboven.

Maak kennis met Ailoot.