This document describes the TodoWrite tool in Claude Code by Anthropic, which provides structured task list management for coding sessions. TodoWrite enables tracking progress across multi-step implementations, organizing complex work, and maintaining visibility into task completion status. The tool is designed for use during active coding sessions where multiple related tasks need systematic tracking.
For information about Claude Code's broader tool ecosystem, see Tool Architecture and Categories. For sub-agent task delegation using the Task tool, see Task Tool and Sub-agent Specialization.
Sources: Anthropic/Claude Code/Tools.json391-433
The TodoWrite tool is defined at Anthropic/Claude Code/Tools.json391-433 as a structured task management system. The tool name is "TodoWrite" Anthropic/Claude Code/Tools.json391 and accepts a single required parameter todos Anthropic/Claude Code/Tools.json429 containing an array of task objects.
JSON Tool Invocation Structure:
All three fields are marked as required at Anthropic/Claude Code/Tools.json417-421: "content" Anthropic/Claude Code/Tools.json401-404 "status" Anthropic/Claude Code/Tools.json405-412 and "id" Anthropic/Claude Code/Tools.json413-415 The tool operates on complete state replacement—each invocation must provide the entire updated todos array.
Sources: Anthropic/Claude Code/Tools.json391-433
Sources: Anthropic/Claude Code/Tools.json391-433
Sources: Anthropic/Claude Code/Tools.json391-432
TodoWrite follows specific activation criteria to determine when task tracking adds organizational value versus when it introduces unnecessary overhead.
The tool should be activated proactively in these scenarios:
| Scenario | Criteria | Rationale |
|---|---|---|
| Complex multi-step tasks | Task requires ≥3 distinct steps/actions | Multiple steps benefit from systematic tracking |
| Non-trivial complexity | Task requires careful planning or multiple operations | Organization prevents missed steps |
| Explicit user request | User directly asks for todo list | Honors user preference for tracking |
| Multiple tasks provided | User provides list (numbered/comma-separated) | Maintains clear scope of work |
| New instructions received | Immediately capture user requirements | Ensures nothing is forgotten |
| Starting task work | Mark as in_progress BEFORE beginning | Provides progress visibility |
| Completing task work | Mark as completed immediately after finishing | Real-time status accuracy |
Sources: Anthropic/Claude Code/Tools.json393-433
| Scenario | Criteria | Rationale |
|---|---|---|
| Single straightforward task | Only one task with clear execution path | No organizational benefit |
| Trivial task | Task provides no tracking benefit | Overhead exceeds value |
| Less than 3 trivial steps | Can be completed quickly | Direct execution is faster |
| Conversational/informational | No actual coding work | Nothing to track |
Sources: Anthropic/Claude Code/Tools.json393-433
Sources: Anthropic/Claude Code/Tools.json393-433
TodoWrite implements a three-state model for task lifecycle management:
pending: Task not yet started. Used for tasks in the queue awaiting execution.
in_progress: Currently working on the task. Critical constraint: ONLY ONE task should be in_progress at any time. This enforces sequential task execution and provides clear progress visibility.
completed: Task finished successfully. Only set when the task is FULLY accomplished without errors, blockers, or partial completion.
Sources: Anthropic/Claude Code/Tools.json393-433
Sources: Anthropic/Claude Code/Tools.json393-433
A task must NOT be marked as completed if any of these conditions exist:
When blocked, the correct approach is to:
in_progressSources: Anthropic/Claude Code/Tools.json393-433
TodoWrite enforces a real-time update pattern where task status changes are reflected immediately, not batched. This ensures the user always sees current progress.
Sources: Anthropic/Claude Code/Tools.json393-433
When creating todos, follow these principles:
Specificity: Create specific, actionable items rather than vague descriptions.
Granularity: Break complex tasks into smaller, manageable steps.
Clarity: Use clear, descriptive task names that indicate what will be accomplished.
Sources: Anthropic/Claude Code/Tools.json393-433
Scenario: User requests "add dark mode toggle to application settings, make sure you run the tests and build when you're done"
Decision: Use TodoWrite - This is a complex multi-step task requiring UI, state management, styling, and verification steps.
Initial Todo List:
todos: [
{ content: "Create dark mode toggle component in Settings page", status: "pending", id: "1" },
{ content: "Add dark mode state management (context/store)", status: "pending", id: "2" },
{ content: "Implement CSS-in-JS styles for dark theme", status: "pending", id: "3" },
{ content: "Update existing components to support theme switching", status: "pending", id: "4" },
{ content: "Run tests and build process, addressing any failures or errors that occur", status: "pending", id: "5" }
]
Rationale: The assistant inferred that tests and build need to pass (not just run) by framing the final task as ensuring success. The user explicitly requested tests and build be executed, making this a clear multi-step task requiring tracking.
Sources: Anthropic/Claude Code/Tools.json393-433
Scenario: User requests "rename the function getCwd to getCurrentWorkingDirectory across my project"
Decision Process:
Decision: Use TodoWrite - After discovery reveals multiple occurrences across different files, systematic tracking prevents missing instances and maintains consistency.
Sources: Anthropic/Claude Code/Tools.json393-433
Scenario: User provides "implement these features for my e-commerce site: user registration, product catalog, shopping cart, and checkout flow"
Decision: Use TodoWrite - User provided multiple complex features in a comma-separated list.
Task Organization: Break down each feature into specific tasks based on project architecture. For example:
Sources: Anthropic/Claude Code/Tools.json393-433
Scenario: User requests "optimize my React application, it's rendering slowly"
Decision Process:
Decision: Use TodoWrite - Performance optimization is non-trivial and requires multiple steps. The systematic approach ensures all bottlenecks are addressed.
Todo List Structure:
todos: [
{ content: "Implement memoization for expensive calculations in ProductList", status: "pending", id: "1" },
{ content: "Add virtualization for long lists in Dashboard", status: "pending", id: "2" },
{ content: "Optimize image loading in Gallery component", status: "pending", id: "3" },
{ content: "Fix state update loops in ShoppingCart", status: "pending", id: "4" },
{ content: "Review bundle size and implement code splitting", status: "pending", id: "5" }
]
Sources: Anthropic/Claude Code/Tools.json393-433
Scenario: User asks "How do I print 'Hello World' in Python?"
Decision: Skip TodoWrite - This is a single, trivial informational request with no actual coding task to complete.
Correct Response: Provide the answer directly without task tracking overhead.
Sources: Anthropic/Claude Code/Tools.json393-433
Scenario: User requests "add a comment to the calculateTotal function to explain what it does"
Decision: Skip TodoWrite - This is a single, straightforward task confined to one location in the code. Task tracking provides no organizational benefit.
Correct Response: Use the Edit tool directly to add the comment.
Sources: Anthropic/Claude Code/Tools.json393-433
Scenario: User asks "run npm install for me and tell me what happens"
Decision: Skip TodoWrite - This is a single command execution with immediate results. No multiple steps to track or organize.
Correct Response: Execute the command using the Bash tool and report results.
Sources: Anthropic/Claude Code/Tools.json393-433
Scenario: User asks "what does the git status command do?"
Decision: Skip TodoWrite - This is purely conversational/informational with no coding task to perform.
Correct Response: Provide the explanation directly.
Sources: Anthropic/Claude Code/Tools.json393-433
TodoWrite serves a different purpose than the Task tool (see Task Tool and Sub-agent Specialization):
Task tool Tools.json4-30: Launches specialized sub-agents with subagent_type parameter Tools.json17-20 Available agent types include "general-purpose", "statusline-setup", and "output-style-setup" Tools.json5-8 Used for heavy implementations requiring autonomous agent context.
TodoWrite tool Tools.json391-433: Tracks the main agent's own work items within the current session using the todos array parameter Tools.json396-425 Provides progress visibility through status field Tools.json405-412
Usage Pattern: TodoWrite may include a task with content: "Delegate X to sub-agent using Task tool" Tools.json401-404 The main agent invokes Task with appropriate subagent_type Tools.json17-20 and prompt Tools.json13-16 Upon sub-agent completion, the TodoWrite task is updated to status: "completed" Tools.json410
Sources: Anthropic/Claude Code/Tools.json4-30 Anthropic/Claude Code/Tools.json391-433
TodoWrite integrates with other Claude Code tools defined in Anthropic/Claude Code/Tools.json The following diagram shows actual tool names and their invocation relationships:
Workflow Pattern with Tool Names:
Grep Tools.json84 Glob Tools.json62 Read Tools.json194 for context gatheringTodoWrite with todos array where all items have status: "pending" Tools.json407TodoWrite to update first task to status: "in_progress" Tools.json409Edit Tools.json220 MultiEdit Tools.json252 Write Tools.json300 or Bash Tools.json32 to perform workTodoWrite to mark task as status: "completed" Tools.json410 and next task as in_progressBash Tools.json32 with test/build commands for validationTodoWrite invocation with all tasks marked completedSources: Anthropic/Claude Code/Tools.json32-60 Anthropic/Claude Code/Tools.json62-82 Anthropic/Claude Code/Tools.json84-149 Anthropic/Claude Code/Tools.json151-173 Anthropic/Claude Code/Tools.json194-217 Anthropic/Claude Code/Tools.json220-250 Anthropic/Claude Code/Tools.json252-297 Anthropic/Claude Code/Tools.json300-320 Anthropic/Claude Code/Tools.json391-433
The TodoWrite tool description at Anthropic/Claude Code/Tools.json392 emphasizes proactive usage: "When in doubt, use this tool. Being proactive with task management demonstrates attentiveness and ensures you complete all requirements successfully."
This philosophy encourages erring on the side of task tracking when complexity is ambiguous, as the organizational benefit typically outweighs the minimal overhead of maintaining the todos array Tools.json396-425
The "ONE task in_progress at a time" rule appears multiple times in the tool description Tools.json392 This constraint enforces the status field Tools.json405-412 having at most one item with value "in_progress" Tools.json409 across the entire todos array:
Implementation: Before setting a new task's status to "in_progress", ensure the current in_progress task has status updated to "completed" Tools.json410 or moved back to "pending" Tools.json407 with a blocker task created.
The status field Tools.json405-412 must be updated in real-time with each TodoWrite invocation, not batched:
status: "in_progress" BEFORE beginning work Tools.json409status: "completed" IMMEDIATELY after finishing Tools.json410todos array for every state change Tools.json396-425The tool description Tools.json392 states: "Remove tasks that are no longer relevant from the list entirely." This means:
todos array Tools.json396-425 once doneSources: Anthropic/Claude Code/Tools.json391-433
TodoWrite is a structured task management tool in Claude Code designed for tracking multi-step coding tasks. It uses a simple three-state model (pending, in_progress, completed) with strict constraints: only one task can be in_progress at a time, and tasks must be marked completed only when fully finished without errors or blockers.
The tool follows clear activation criteria: use it for complex tasks (≥3 steps), non-trivial work, multiple user-provided tasks, or when explicitly requested. Skip it for single straightforward tasks, trivial operations, or purely conversational interactions.
TodoWrite integrates with Claude Code's broader tool ecosystem, particularly complementing the Task tool for sub-agent delegation and working alongside file operations (Read, Edit, Write) and validation tools (Bash) in typical development workflows.
Refresh this wiki