Ask Claude Code to do five things in one message and one of two things happens: it does all five, in order, checking each off as it goes — or it does three, quietly drops two, and tells you it's done. The difference is whether TodoWrite is in the loop.
TodoWrite is Claude Code's built-in task list. It is not a chat feature, not a summary Claude writes for your benefit — it's a structured state object the model reads and writes to between tool calls, and it is the single biggest lever for keeping a long agent session honest about what's actually finished.
What TodoWrite Actually Is
TodoWrite is a tool call, same category as Edit or Bash. When invoked, it replaces the entire task list with a new array of items, each carrying three fields:
{
"content": "Fix the auth redirect bug",
"activeForm": "Fixing the auth redirect bug",
"status": "in_progress"
}content is the imperative form shown once a task is done or pending. activeForm is the present-continuous form shown while a task is running — this is why you see "Fixing the auth redirect bug" flash in the UI instead of a static bullet list. status is one of three values: pending, in_progress, or completed. There is no fourth state for "partially done" or "blocked" — a task that can't finish gets a new pending task describing the blocker instead.
The Rule That Matters: One Task In Progress at a Time
Claude Code is instructed to keep exactly one item marked in_progress at any moment, and to mark it completed the instant the work is done — not batched at the end of the turn. This single constraint is what prevents the most common failure mode in long sessions: the model reporting five things complete when only the first one actually ran.
In practice this means the todo list is a live progress bar, not a plan written once and forgotten. Watch a session working through a multi-file refactor and you'll see items flip from pending to in_progress to completed one at a time, in the exact order the work happens — including new items appearing mid-session when the model discovers a step it didn't originally plan for.
When TodoWrite Fires Automatically
You don't ask for a todo list — Claude Code decides to create one based on task shape. The triggers that reliably produce a list:
- Multi-step tasks. Anything needing three or more distinct actions (edit this file, run this test, fix what breaks) gets tracked.
- Non-trivial complexity. A single "rename this variable" edit won't get a list. "Migrate this component to the new API and update its tests" will.
- Explicit multi-task requests. A numbered or comma-separated list of asks from you ("add X, fix Y, and refactor Z") almost always produces a matching todo list.
- New instructions mid-task. If you interject a new requirement while work is in progress, it gets appended as a new pending item rather than silently folded into the current one.
Conversely, single, unambiguous, low-step actions skip the list entirely — there's no value in tracking "read this file" as a task. If you notice Claude Code isn't tracking something you expected it to, it's usually because the task genuinely collapses to one step, not because the tool is broken.
Why This Beats Asking Claude to "Just Remember"
Context windows are long but attention inside them isn't uniform — a plan stated in prose at the start of a session degrades as more tool output, file contents, and back-and-forth accumulate. A todo list is different: it's re-surfaced as structured state on every relevant turn, not buried in scrollback. That's the same reason we recommend CLAUDE.md for durable project rules instead of repeating them in chat — structured, persistent state beats prose the model has to remember to reread.
It also gives you, the human, a cheap way to audit progress without reading the whole transcript. Glance at the todo list and you know exactly what's done, what's running, and what's still queued — which matters most in headless automation where nobody is watching the session live.
TodoWrite vs. Plan Mode
These solve adjacent but different problems. Plan mode is about the decision before work starts — analyzing the codebase, proposing an approach, and getting your explicit go-ahead before anything gets touched. TodoWrite is about execution after that decision is made — tracking the steps of the approach you already approved.
A typical flow: plan mode produces the approach, you approve it, and the approved plan becomes the initial todo list. From there, TodoWrite takes over as the source of truth for what's done.
TodoWrite and Checkpoints
If a session goes sideways and you use rewind to roll back to an earlier point, the todo list rolls back with it — tasks that were marked completed after the checkpoint go back to pending. This is correct behavior: the file changes and the task-tracking state should always agree on what's actually been done. A todo list that says "completed" for work that rewind just undid would be worse than no tracking at all.
Working With TodoWrite in Practice
You can't hand-edit it
There's no UI for manually checking off a box — TodoWrite is a tool the model calls, not a checklist you interact with directly. If you want a task removed or reprioritized, say so in chat and Claude Code will issue a new TodoWrite call with the updated list.
Long sessions benefit most
For a two-minute fix, the overhead of tracking isn't worth noticing. For a session spanning dozens of tool calls — a migration, a multi-file feature build, a subagent-delegated research task — the todo list is what keeps the session coherent when the original request is long since scrolled off screen.
It doesn't replace your own project tracker
TodoWrite is scoped to a single session. It has no memory of yesterday's session and no integration with Jira, Linear, or GitHub Issues. Treat it as a live scratchpad for the current unit of work, not a system of record — for that, you still want your actual project management tool, with Claude Code's session-level list feeding into it, not replacing it.
The Bottom Line
TodoWrite is the difference between an agent that tells you it finished and an agent whose state you can verify finished. It fires automatically on multi-step work, enforces one-task-at-a-time execution, and stays honest through rewinds. You don't configure it and you don't need to ask for it — you just need to recognize when it's missing, because that's usually a sign the task was smaller than you thought, or a sign something's off.
Want Claude Code Wired Into Your Actual Workflow?
Our consulting team builds production agent workflows — task tracking, CI/CD integration, and everything between plan mode and deploy.