Background-Sessions mit Claude Agents: lange Tasks laufen lassen ohne dein Terminal zu blockieren

Du startest einen größeren Task, eine Migration, ein Test-Refactor, ein Doku-Durchlauf über zwanzig Dateien, und dann sitzt du da und schaust deinem Terminal beim Arbeiten zu. Eine Stunde lang. In der Zeit ist die Session belegt, du kannst nichts anderes machen, und wenn du das Fenster zumachst, ist die Arbeit weg. Genau dafür gibt es den claude agents Befehl. Er dispatcht eine Session in den Hintergrund, gibt dir dein Terminal sofort zurück und lässt Claude weiterarbeiten während du an was anderem sitzt. Später holst du die Session mit --resume zurück, schaust rein, gibst Feedback, machst weiter. Wir richten das jetzt ein und ich zeig dir die Stolperfallen die mich am Anfang Zeit gekostet haben.

Schritt 1, kapier den Unterschied zwischen interaktiv und dispatched

Eine normale Claude-Code-Session ist interaktiv. Du tippst, Claude antwortet, du wartest, du tippst wieder. Das ist gut für Arbeit bei der du eng dabei sein willst. Eine Background-Session ist anders. Du gibst ihr einen Auftrag, sie läuft los, und du bist nicht mehr im Loop bis du sie wieder öffnest. Der Befehl dafür ist claude agents. Er dispatcht eine oder mehrere Sessions die im Hintergrund laufen, mit eigenen Defaults für Modell, Effort und Permissions.

Wichtig zum Erwartungsmanagement: Background heißt nicht autonom-und-vergiss. Du gibst die Permission-Regeln mit, und alles was du nicht erlaubt hast, wartet trotzdem auf dich. Eine Background-Session die bei jedem git push hängen bleibt weil du keine Permission gesetzt hast, hat dir nichts gebracht. Die halbe Arbeit in diesem Playbook ist deshalb, die Defaults so zu setzen dass die Session wirklich durchläuft.

Schritt 2, dispatch deine erste Background-Session

Der Einstieg ist ein einziger Befehl. Du gibst claude agents mit dem Modell und dem Effort den du willst, und einem klaren Auftrag.

claude agents --model sonnet --effort medium

Die offiziell dokumentierten Flags für claude agents sind --add-dir, --settings, --mcp-config, --plugin-dir, --permission-mode, --model, --effort und --dangerously-skip-permissions. Die setzen die Defaults für die dispatched Session. Faustregel für den Anfang: nimm --model sonnet für normale Arbeit, --effort medium, und lass die Finger von --dangerously-skip-permissions bis du verstanden hast was die Session anfasst. Der Grund steht in Schritt 7.

Schritt 3, gib der Session einen Namen statt einer kryptischen ID

Background-Sessions kriegen eine Session-ID. Die ist eindeutig, aber niemand merkt sich a3f9c1e2-.... Innerhalb einer Session kannst du sie mit /rename umbenennen, und dann holst du sie später über den Namen statt über die ID zurück.

/rename test-refactor-juni

Mach das gleich am Anfang jeder Background-Session die länger als ein paar Minuten läuft. Wenn du drei davon parallel hast, ist der Unterschied zwischen "welche war nochmal die mit den Tests" und einem klaren Namen genau der zwischen entspannt und genervt.

Schritt 4, hol die Session mit resume zurück

Das ist der Kern. Eine Background-Session arbeitet weiter während du weg bist, und wenn du reinschauen willst, holst du sie zurück. Drei Befehle die du dir merken solltest:

# Eine bestimmte Session ueber ihre ID
claude --resume <session-id>

# Eine benannte Session im Print-Mode
claude -p --resume test-refactor-juni

# Einfach die letzte Session weiterfuehren
claude --continue

--resume mit ID oder Name öffnet genau die Session die du willst. --continue nimmt die letzte. Der Print-Mode -p gibt dir die Antwort direkt auf stdout statt in die interaktive Oberfläche, das ist praktisch wenn du nur schnell den Stand sehen willst ohne in die Session reinzuspringen.

Schritt 5, lass Background-Sessions im richtigen Verzeichnis arbeiten

Standardmäßig isoliert Claude Code Background-Sessions in einem Git-Worktree, damit sie deine Arbeitskopie nicht unter den Füßen wegziehen während du selbst im Repo tippst. Das ist meistens richtig. Manchmal ist es im Weg, zum Beispiel bei Repos wo Worktrees umständlich sind oder die Build-Pipeline mit zwei Arbeitskopien Probleme macht.

Dafür gibt es die Einstellung worktree.bgIsolation in deiner settings.json. Setzt du sie auf "none", darf die Background-Session direkt in der Arbeitskopie editieren statt in einem isolierten Worktree.

{
  "worktree": {
    "bgIsolation": "none"
  }
}

Mein Rat: lass die Isolation an solange du parallel selbst im Repo arbeitest. Schalt sie nur ab wenn du genau einen Grund hast und weißt dass keine zweite Session gleichzeitig dieselben Dateien anfasst. Zwei Prozesse die unkoordiniert in dieselbe Arbeitskopie schreiben, ist der schnellste Weg zu einem Merge-Chaos das du von Hand aufräumen darfst.

Schritt 6, gib der Session ihren Kontext per SessionStart-Hook

Eine Background-Session startet kalt. Sie weiß nicht was du weißt, außer was in der CLAUDE.md steht. Wenn du willst dass sie mit dem richtigen Kontext losläuft, ohne dass du ihn jedes Mal in den Prompt tippst, nimm den SessionStart-Hook. Der feuert wenn eine Session beginnt und kann Kontext laden, eine Umgebung setzen oder eine Notiz aus deinem Memory ziehen.

Ein minimaler SessionStart-Hook in der settings.json sieht so aus:

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          { "type": "command", "command": "cat .claude/context-brief.md" }
        ]
      }
    ]
  }
}

Der Output landet im Kontext der startenden Session. Bei uns lädt der Hook einen kurzen Brief mit dem aktuellen Stand, sodass jede Background-Session direkt weiß in welchem Projekt sie ist und welche Regeln gelten. Wenn du das in der Academy noch nicht aufgesetzt hast, lies vorher die Lesson zu Hooks und Skills, das gehört zusammen.

Schritt 7, sei vorsichtig mit dangerously-skip-permissions im Hintergrund

--dangerously-skip-permissions winkt alle Tool-Aufrufe blind durch. In einer interaktiven Session ist das schon riskant, weil ein verseuchtes Paket oder eine Prompt-Injection genau diese Tür nimmt. In einer Background-Session ist es schlimmer, weil du nicht danebensitzt. Die Session feuert rm, npm install und git push ohne dass du es in dem Moment mitkriegst.

Der bessere Weg ist --permission-mode mit einer durchdachten Permission-Allowlist in deinen Settings. Erlaub konkret die Befehle die der Task braucht, und lass den Rest blockieren. Wenn die Session dann an einer nicht erlaubten Aktion hängt, holst du sie mit --resume zurück, schaust dir an was sie wollte und entscheidest. Das ist eine Minute Mehraufwand und spart dir den Tag an dem eine Background-Session was kaputtmacht das du erst zwei Stunden später siehst. Wenn du Bash-Befehle generell absichern willst, schau dir das Playbook zur Bash-Sandbox an, das ergänzt sich gut.

Schritt 8, dispatch mehrere Sessions für parallele Arbeit

Der eigentliche Hebel kommt wenn du mehrere Background-Sessions parallel laufen lässt. Eine schreibt Tests, eine macht das Doku-Update, eine räumt ein Modul auf. Jede kriegt ihren eigenen Namen über /rename, ihre eigenen Defaults beim Dispatch, und du sammelst die Ergebnisse ein wenn sie fertig sind.

Wichtig dabei: gib jeder Session einen scharf abgegrenzten Auftrag. Drei Sessions die alle am selben Modul schrauben, treten sich gegenseitig auf die Füße, besonders wenn du die Worktree-Isolation aus Schritt 5 abgeschaltet hast. Drei Sessions die an drei verschiedenen Ecken arbeiten, sind echte Parallelität. Das Pattern ist dasselbe wie bei parallelen interaktiven Sessions mit Git-Worktrees, nur dass du nicht in jeder davon selbst sitzt.

Schritt 9, baue dir eine Routine zum Einsammeln

Background-Sessions haben einen blinden Fleck. Wenn du nicht reinschaust, weißt du nicht ob sie fertig, blockiert oder in eine falsche Richtung gelaufen sind. Mein Setup dagegen ist simpel: einmal am Vormittag und einmal am späten Nachmittag gehe ich die offenen Sessions durch. --resume rein, Stand lesen, Feedback geben oder abnicken, raus.

Wenn du das automatisieren willst, kombinier es mit den scheduled Routines aus dem entsprechenden Playbook. Eine Routine die dir zweimal täglich eine kurze Übersicht der laufenden Sessions in den Chat oder per Notification schickt, nimmt dir das Hinterherrennen ab. Der Punkt ist nicht die Technik, der Punkt ist die Gewohnheit. Eine Background-Session die niemand einsammelt, ist eine Session die du auch gleich hättest sein lassen können.

Schritt 10, räum auf und benenne konsequent

Nach ein paar Tagen mit Background-Sessions hast du eine Liste alter Sessions die nichts mehr tun. Geh die durch, hol abgeschlossene mit --resume einmal rein um sicher zu sein dass nichts offen ist, und lass sie dann liegen. Was bleibt, ist die Disziplin beim Benennen. Eine konsistente Namens-Konvention, zum Beispiel task-modul-datum, macht den Unterschied zwischen einer brauchbaren Session-Liste und einem Haufen kryptischer IDs.

Mein Fehler am Anfang war, alles über --continue zu fahren weil das am bequemsten ist. Dann hatte ich drei Background-Sessions und --continue hat immer die zuletzt berührte genommen, nicht die die ich meinte. Seitdem benenne ich jede Session die länger als zehn Minuten lebt sofort mit /rename und hole sie über den Namen. Klingt nach Kleinkram, ist aber der Unterschied zwischen "ich weiß was läuft" und "warum hat die das jetzt geändert".

Was als nächstes

Wenn Background-Sessions sitzen, ist der nächste logische Schritt das Headless-Setup für CI/CD, also Claude Code ganz ohne Terminal in einer Pipeline. Dafür gibt es ein eigenes Playbook. Und wenn du anfängst mehrere Sessions parallel zu fahren, lies das Playbook zu parallelen Sessions mit Git-Worktrees, das erklärt die Isolation aus Schritt 5 ausführlicher. Auf Level 5 in der Academy geht es ums CEO-Worker-Pattern, das ist die nächste Stufe wenn du nicht nur Sessions parallel laufen lassen, sondern sie auch koordinieren willst.

Source

Specs verifiziert gegen das offizielle Claude Code CHANGELOG und die CLI-Referenz:

• Claude Code CHANGELOG (claude agents Flags, worktree.bgIsolation, resume mit ID und Name): https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md
• Claude Code CLI-Referenz: https://code.claude.com/docs/en/cli-reference
• SessionStart-Hook: https://code.claude.com/docs/en/hooks