So lässt du Claude Code als Hintergrund-Agent laufen

Fünf Wege, Claude Code im Hintergrund auszuführen

Sie unterscheiden sich darin, was weiterlaufen muss und wer die Arbeit startet.

Background Tasks innerhalb einer Session

Drück Ctrl+B, während Claude einen Bash-Befehl oder einen Subagenten ausführt, um ihn in den Hintergrund zu schicken (in tmux zweimal), und sprich weiter mit Claude. Claude kann einen Befehl auch von sich aus im Hintergrund starten. Subagenten, die Claude startet, laufen standardmäßig im Hintergrund.

Tippe /tasks, um laufende Shells und Subagenten aufzulisten und nach ihnen zu sehen. In einer lokalen Terminal-Session hat ein Hintergrundbefehl kein Zeitlimit, er endet aber, wenn Claude Code beendet wird. Wie du mehrere Agenten nebeneinander laufen lässt, steht in mehrere Claude-Code-Agenten parallel ausführen.

Agent View: Sessions, die das Terminal überdauern

claude --bg "<prompt>" startet eine Session im Hintergrund und kehrt sofort zurück; /bg schickt die Session, in der du gerade bist, in den Hintergrund. Ein Supervisor-Prozess führt sie aus, das Schließen des Terminals stoppt sie also nicht, das Herunterfahren oder Neustarten des Computers aber schon, und eine nicht verbundene, untätige Session wird nach etwa einer Stunde beendet.

claude agents öffnet die Agent View; mit claude attach <id>, claude logs <id> und claude stop <id> verwaltest du eine einzelne Session. Agent View ist eine Research Preview, die Befehle können sich also ändern.

Claude Code headless mit claude -p ausführen

1. Einen Prompt ausführen und beenden

   -p (oder --print) führt Claude Code ohne die interaktive Oberfläche aus und beendet es, wenn es fertig ist, bei Erfolg mit Exit-Code 0. Du kannst auch Eingaben hineinpipen.

   claude -p "List the failing tests and why they fail"
   cat error.log | claude -p "Explain this error"

2. Ausgabe erzeugen, die ein Skript lesen kann

   --output-format json gibt das Ergebnis mit der Session-ID und Metadaten zurück, darunter total_cost_usd, eine auf deinem Rechner berechnete Schätzung. stream-json (mit --verbose) streamt Ereignisse, sobald sie passieren.

   claude -p "Summarize this repo" --output-format json | jq -r '.result'

3. Nur die Tools erlauben, die es braucht

   Im Headless-Modus ist niemand da, der eine Abfrage freigibt. Seit v2.1.302 startet ein Lauf ohne gesetzten Modus in Manual und lehnt alles ab, was eine Freigabe bräuchte. Nutze --allowedTools für das, was es darf, und --permission-mode dontAsk, damit der Rest abgelehnt wird, statt zu warten.

   claude -p "Run the test suite and summarize failures" \
     --permission-mode dontAsk --allowedTools "Read,Bash(npm test)"

4. Den Lauf begrenzen

   --max-turns stoppt nach einer bestimmten Zahl von Agent-Turns, --max-budget-usd bei geschätzten Kosten (es kann etwas darüber hinausgehen). Beides funktioniert nur mit -p.

   claude -p "Fix the lint errors" --max-turns 15 --max-budget-usd 3

5. Dieselbe Unterhaltung später fortsetzen

   Speichere die Session-ID aus der JSON-Ausgabe und übergib sie an --resume, oder nutze --continue für die letzte Session im Verzeichnis.

   id=$(claude -p "Start a code review of src/" --output-format json | jq -r '.session_id')
   claude -p "Now check the tests too" --resume "$id"

6. Nach Zeitplan mit cron ausführen

   Die Dokumentation von Anthropic enthält kein Cron-Beispiel; dieses hier nutzt nur dokumentierte Flags. Cron hat einen minimalen PATH, nutze also den vollständigen Pfad aus which claude und leg den Log-Ordner vorher an. Füge hier kein --bare hinzu: Es überspringt deine Abo-Anmeldung und braucht einen API-Key.

   # crontab -e: werktags um 9:00 Uhr
   0 9 * * 1-5  cd /path/to/repo && /path/to/claude -p "Summarize yesterday's commits and list new TODO comments. Do not edit files." --permission-mode dontAsk --allowedTools "Read,Bash(git log *),Bash(git diff *)" --max-turns 10 --output-format json >> "$HOME/logs/claude-daily.log" 2>&1

Quelle: Dokumentation von Anthropic zum Headless-Modus (Englisch)

Berechtigungen für unbeaufsichtigte Läufe

• dontAsk plus eine --allowedTools-Liste ist die abgeriegelte Variante: Alles, was nicht auf der Liste steht, wird abgelehnt.
• auto lässt einen Klassifikator statt dir jede Aktion prüfen. Anthropic weist darauf hin, dass das keine Sicherheit garantiert.
• acceptEdits gibt Dateiänderungen und einfache Dateibefehle frei, aber keine anderen Shell-Befehle.
• bypassPermissions überspringt Abfragen und Sicherheitsprüfungen. Laut Anthropic solltest du es nur in isolierten Containern oder VMs ohne Internetzugang nutzen, da es keinen Schutz vor Prompt Injection bietet.
• Für Regeln, die für jeden Lauf in einem Projekt gelten, trag permissions.allow und permissions.deny in .claude/settings.json ein. Deny-Regeln haben immer Vorrang.

Cloud-Optionen: wenn dein Computer aus ist

• Cloud-Sessions: claude --cloud "<task>" läuft auf der Infrastruktur von Anthropic, ausgehend von deinem GitHub-Branch, und arbeitet bei zugeklapptem Laptop weiter. Folgeanweisungen schickst du mit claude -p "..." --cloud <session-id>.
• Cloud scheduled tasks: angelegt mit /schedule oder unter claude.ai/code, laufen sie nach Zeitplan (höchstens stündlich), per API-Aufruf oder bei GitHub-Ereignissen. Pro, Max, Ultra, Team und Enterprise; Research Preview.
• GitHub Actions: anthropics/claude-code-action@v1 mit einem schedule-Trigger. Ein OAuth-Token aus claude setup-token nutzt dein Abo; ein API-Key wird pro Token abgerechnet.

Gib einem Hintergrund-Agenten eine feste Aufgabe

Background Tasks, Agent View und cron starten alle Arbeit, über die du schon entschieden hast. Crewmark gibt einer Claude-Code-Session stattdessen eine dauerhafte Rolle: Sie wacht während der Arbeitszeit im Heartbeat-Takt auf, nimmt das nächste Issue vom Board und schreibt dir, wenn sie blockiert ist.

1. Mach aus einer Session einen Mitarbeiter

   Wähle eine Rolle und ein Ziel in Zahlen und führe den Setup-Befehl, den Crewmark dir gibt, in Claude Code aus. Diese Unterhaltung wird zum Mitarbeiter.

2. Lass den Heartbeat die Arbeit starten

   Der Crewmark-Daemon weckt die Session während ihrer Arbeitszeit alle 15, 30 oder 60 Minuten, mit dem Abo, für das du schon zahlst, und lässt sie außerhalb davon in Ruhe.

3. Issues zuweisen, Nachrichten beantworten

   Leg Arbeit als Issues auf dem Board an; der Mitarbeiter übernimmt sie, kommentiert unterwegs und fragt dich, wenn er ein Review braucht. Siehe was ein KI-Mitarbeiter ist.

FAQ zu Claude Code als Hintergrund-Agent