Skip to main content
Claude Code stellt die Task-Tracking-Tools standardmäßig nur auf den unter Modellverfügbarkeit aufgelisteten Modellen bereit. Neuere Modelle verfolgen mehrstufige Arbeiten ohne eine schriftliche Todo-Liste, daher benötigen Sie auf diesen nichts auf dieser Seite, damit Claude mehrstufige Aufgaben durcharbeitet. In einer Sitzung, die die Task-Tracking-Tools hat, führt Claude eine schriftliche Todo-Liste, aktualisiert den Status jedes Elements während der Arbeit. Sie sehen jede Änderung im Nachrichtenstrom als strukturierten Tool-Aufruf. Aktivieren Sie eine Sitzung nur, wenn Ihre Anwendung diese Tool-Aufrufe liest, sei es zum Protokollieren von Task-Aktivitäten oder zum Rendern einer eigenen Fortschrittsanzeige.

Modellverfügbarkeit

Die folgenden Tools sind standardmäßig nur auf Claude Opus 4.7, Claude Sonnet 4.6, Claude Haiku 4.5 und früheren Modellen verfügbar. Bei allen anderen Modellen, einschließlich Modell-IDs, die Claude Code nicht erkennt, sind sie nicht verfügbar, es sei denn, Sie aktivieren sie:
  • TodoWrite
  • TaskCreate
  • TaskGet
  • TaskUpdate
  • TaskList
Überall dort, wo die Tools verfügbar sind, stellt Claude Code die vier Task-Tools bereit, oder TodoWrite, wenn Sie CLAUDE_CODE_ENABLE_TASKS=0 setzen.Dieser Standardsatz gilt in Claude Code v2.1.268 und später, das das TypeScript Agent SDK ab v0.3.268 bündelt.
Bei einem Modell, das die Tools standardmäßig nicht hat, sehen Sie keine tool_use-Blöcke für diese im Nachrichtenstrom, es sei denn, Sie aktivieren eine Sitzung. Das Agent SDK wendet diese Standardeinstellungen über die Claude Code-Binärdatei an, die es bündelt. Wenn Sie pathToClaudeCodeExecutable (TypeScript) oder cli_path (Python) auf Ihre eigene Claude Code-Installation verweisen, erhalten Sie die Tools, die diese Installation bereitstellt, unter ihren eigenen Standardeinstellungen. Um die genaue Menge in einer laufenden Sitzung zu sehen, überprüfen Sie, welche Tools verfügbar sind. Um eine Sitzung zu aktivieren, führen Sie eines der folgenden Verfahren durch:
  • Nennen Sie eines der Tools in der Option allowedTools (TypeScript) oder allowed_tools (Python)
  • Listen Sie die Tools in der Option tools auf, die die integrierten Tools der Sitzung auf die beschriebenen beschränkt. Fügen Sie die gewünschten Tools neben den anderen integrierten Tools ein, die Sie verwenden
  • Setzen Sie CLAUDE_CODE_ENABLE_TODO_TOOLS=1 in der Option env, wie die Beispiele auf dieser Seite. In TypeScript ersetzt env die Subprocess-Umgebung, daher verteilen Sie ...process.env, um vererbte Variablen zu behalten. In Python wird env auf die vererbte Umgebung zusammengeführt

Todo-Lebenszyklus

Claude bewegt jedes Todo durch einen vorhersehbaren Lebenszyklus:
  1. Erstellt: Claude fügt das Todo als pending hinzu, wenn es eine Aufgabe identifiziert
  2. Aktiviert: Claude setzt das Todo auf in_progress, wenn es die Arbeit beginnt
  3. Abgeschlossen: Claude markiert es als abgeschlossen, wenn die Aufgabe erfolgreich beendet wird
  4. Entfernt: Claude löscht ein Todo, das es nicht mehr benötigt, indem es status: "deleted" in einem TaskUpdate-Aufruf setzt

Wann Claude Todos erstellt

In einer Sitzung, die die Task-Tracking-Tools hat, erstellt Claude Todos für die meisten mehrstufigen Arbeiten, wie zum Beispiel:
  • Komplexe mehrstufige Aufgaben, die drei oder mehr unterschiedliche Aktionen erfordern
  • Von Benutzern bereitgestellte Aufgabenlisten, wenn mehrere Elemente erwähnt werden
  • Längere Operationen, die von der Fortschrittsverfolgung profitieren
  • Explizite Anfragen, wenn Benutzer um Todo-Organisation bitten
Claude kann Todos für sehr kurze oder einstufige Anfragen überspringen.

Beispiele

Bevor Sie diese Beispiele ausführen, installieren Sie das Claude Agent SDK, indem Sie dem Schnellstart folgen. Jedes Beispiel auf dieser Seite teilt die gleiche Berechtigungseinrichtung und das gleiche Beendigungsverhalten:
  • Berechtigungsmodus: Die Beispiel-Prompts bitten Claude, echte Arbeit an einem Projekt zu leisten, daher setzt jedes Beispiel permissionMode: "acceptEdits" (TypeScript) oder permission_mode="acceptEdits" (Python), um die Dateibearbeitungen, die die Arbeit erzeugt, automatisch zu genehmigen. Siehe Berechtigungsmodi für die Alternativen.
  • Turnus-Limit: Jedes Beispiel wird ausgeführt, bis der Agent fertig ist und seine endgültige Ergebnismeldung liefert. Wenn eine Sitzung zuerst ihr Turnus-Limit erreicht, hat diese Ergebnismeldung den Subtyp error_max_turns. Überprüfen Sie subtype, um dieses Ende zu erkennen.
  • Fehlerbehandlung: Diese Beispiele verwenden Single-Shot-query()-Aufrufe. Nach dem Liefern eines error_max_turns-Ergebnisses wirft query() einen Fehler aus, der Reached maximum number of turns enthält. Jedes Beispiel umhüllt seine Schleife in einem Try-Block, um sauber zu beenden, wenn dies geschieht. Siehe Handle the result für die Ergebnis-Subtypen.
Die Task-Systemmeldungen, SDKTaskNotificationMessage (TypeScript) oder TaskNotificationMessage (Python) unter ihnen, berichten über Hintergrund-Tasks wie backgroundete Befehle und Sub-Agenten. Im Nachrichtenstrom sehen Sie Todo-Aktivität als tool_use-Blöcke in den Assistent-Meldungen.

Überwachen Sie Todo-Änderungen

Das folgende Beispiel beobachtet den Assistent-Stream auf TaskCreate- und TaskUpdate-tool_use-Blöcke und druckt eine +-Zeile mit dem Betreff jeder neuen Aufgabe und eine Update-Zeile mit der Task-ID und dem neuen Status jeder Statusänderung. Verwenden Sie diese Form, wenn Sie ein Protokoll der Task-Aktivität statt einer gerenderten Anzeige möchten. Die +-Zeilen enthalten nicht die zugewiesenen IDs, daher kann dieses Protokoll Updates nicht zurück zu ihren Erstellungen abgleichen. Um diese Korrelation zu behalten, erfassen Sie die IDs wie Zeigen Sie den Fortschritt in Echtzeit an. Die gestreamte tool_use-Eingabe ist die rohe Form, die das Modell ausgegeben hat. Claude Code repariert einige nahezu korrekte, aber fehlerhafte Schlüsselnamen vor der Ausführung, indem es id oder task_id auf taskId und active_form auf activeForm abbildet, aber diese Reparatur wird nicht im Stream widergespiegelt. Lesen Sie TaskUpdate-Eingabefelder defensiv, wie beide Beispiele auf dieser Seite, anstatt anzunehmen, dass der kanonische Name immer vorhanden ist.

Zeigen Sie den Fortschritt in Echtzeit an

Das folgende Beispiel beobachtet den Assistent-Stream auf TaskCreate- und TaskUpdate-tool_use-Blöcke und führt eine Zuordnung von Tasks mit Task-ID in einer TaskTracker-Klasse, wobei eine Fortschrittszusammenfassung bei jeder Änderung neu gerendert wird. Die Zusammenfassung zählt abgeschlossene und laufende Tasks und zeigt das activeForm-Label jedes aktiven Elements anstelle seines subject. Verwenden Sie diese Form, wenn Ihre Anwendung eine Fortschrittsanzeige führt, anstatt jedes Ereignis zu protokollieren. Die zugewiesene Task-ID befindet sich nicht in der TaskCreate-Eingabe. Claude Code liefert die strukturierte Ausgabe jedes Tools in der Benutzermeldung, die seinen tool_result-Block trägt, im Feld tool_use_result. Für TaskCreate ist dieses Objekt für TypeScript als TaskCreateOutput unter Tool-Ausgabetypen dokumentiert, und in Python ist das Feld ein einfaches Dict der gleichen Form. Der Tracker paart jeden tool_result-Block mit seinem tool_use-Aufruf nach tool_use_id und liest task.id aus dem tool_use_result der gepaarten Meldung. Claude kann die Liste mit TaskList zurücklesen und die vollständigen Details einer Task mit TaskGet.