The Todo System in Claude Code: When and How to Use It
Claude Code has a built-in todo system that tracks multi-step tasks within a session. Claude creates and updates todos automatically for complex work — you don't have to manage them. The system shines for tasks with 4+ sequential steps, where losing track of where you left off would cost meaningful time. This guide covers how the todo system works and when to engage it explicitly.
How Claude Code Todos Work
When you ask Claude Code for something that requires multiple steps, it can create a todo list internally and check off items as it completes them. You see this as a running task panel in the UI.
Todos are:
- Session-scoped: They exist for the duration of a conversation, not across sessions
- Auto-created: Claude decides when to create them based on task complexity
- Visible in real-time: You watch items get checked off as Claude works
- Interruptible: You can ask Claude to stop, reprioritize, or add items
When Claude Creates Todos Automatically
Claude creates a todo list when:
- The task has 4+ distinct steps — "Add auth, update the API, add tests, update docs"
- Steps have dependencies — Step B requires Step A to be done first
- The task will take many tool calls — Reading multiple files, running multiple commands
- There's a risk of losing context — Long session where the original goal might drift
Example that triggers auto-todo:
claude "Refactor the authentication system:
- Replace custom JWT with Clerk
- Update all API routes to use Clerk's auth()
- Remove old jwt library and types
- Update CLAUDE.md with new auth pattern
- Run typecheck and fix errors"
Claude will automatically create a 5-item todo list and work through it systematically.
Asking for a Todo List Explicitly
For complex tasks, you can request a todo list before Claude starts working:
# Show me the plan before executing
claude "Before you start: create a todo list for migrating our Prisma schema
to use soft deletes on User, Product, and Order models.
Show me the list and wait for my approval."
Claude responds with something like:
Here's my plan:
1. [ ] Add `deletedAt DateTime?` to User model in schema.prisma
2. [ ] Add `deletedAt DateTime?` to Product model
3. [ ] Add `deletedAt DateTime?` to Order model
4. [ ] Create migration: `prisma migrate dev --name add_soft_delete`
5. [ ] Update findMany queries in lib/db/users.ts to filter deletedAt IS NULL
6. [ ] Update findMany queries in lib/db/products.ts
7. [ ] Update findMany queries in lib/db/orders.ts
8. [ ] Run typecheck and fix errors
9. [ ] Update CLAUDE.md with soft delete pattern
Proceed?
This lets you spot problems in the plan (wrong file paths, missing steps) before any code is written.
Managing Todos During a Session
Adding items mid-task
# While Claude is working
"Add to the list: also update the admin panel queries in lib/db/admin.ts"
Reprioritizing
# Stop current work and shift focus
"Put the CLAUDE.md update last — focus on the database migrations first"
Checking status
# Ask what's left
"What's still on the list?"
Stopping at a checkpoint
# Complete current item and stop
"Finish what you're doing on step 3, then pause.
I want to review before you continue."
Pattern: Large Codebase Refactors
Todo lists are most useful for refactors that touch many files:
claude "Todo list for this refactor:
We're renaming `organizationId` to `orgId` everywhere in the codebase.
Generate a comprehensive todo list covering:
1. Find all occurrences (TypeScript files, schema, env vars, docs)
2. Order by dependency (schema first, then DB queries, then components)
3. Include typecheck after each major section
4. Flag anything that might break tests separately
Don't start yet — just the list."
Claude will audit the codebase first, then produce a sequenced list like:
Refactor Plan: organizationId → orgId
Schema and DB layer:
1. [ ] Update schema.prisma: rename organizationId field on all models
2. [ ] Run prisma migrate dev --name rename_org_id
3. [ ] Update all queries in lib/db/ (12 files)
4. [ ] Run: bun run typecheck
API layer:
5. [ ] Update API routes in app/api/ (8 files)
6. [ ] Update server actions in app/actions/ (4 files)
7. [ ] Run: bun run typecheck
Frontend:
8. [ ] Update component props and hooks (15 components)
9. [ ] Update types in types/api.ts
10. [ ] Run: bun run typecheck
Cleanup:
11. [ ] Search for any remaining references: rg "organizationId"
12. [ ] Update CLAUDE.md with new naming convention
13. [ ] Run full test suite
Pattern: Feature Implementation
claude "Create a todo list for implementing product reviews:
- Users can leave a 1-5 star rating + text review on any product
- Reviews require purchase verification
- Products show average rating
- Admin can delete reviews
Generate the implementation todo list. I'll approve, then you execute."
Good todo lists include:
- DB schema first
- API layer second
- Frontend last
- Typechecks between layers
- Test coverage as explicit items
What Todos Are NOT Good For
Don't use todos for:
- Single-step tasks: "Fix this bug" doesn't need a list
- Short sessions: If it takes 3 minutes, the list adds overhead
- Exploratory work: "Investigate why this is slow" — exploration doesn't have predefined steps
- Pair debugging: When you're iterating interactively, todos slow the conversation
The rule of thumb: if you could describe the work as a numbered list before asking, todos help. If the work is more "figure out what's wrong," skip them.
Todos and Session Context
Todos are session-scoped. When you start a new session, the todo list is gone. For tasks that span multiple sessions:
- End each session with a status update: "Summarize what we completed and what's left"
- Save the remaining items to a file or CLAUDE.md:
claude "We're stopping for today. Write the remaining items from our todo list
to a file called TODO-refactor.md in the project root."
- Start the next session by reading that file:
claude "@TODO-refactor.md Continue from where we left off.
Show me what's remaining before you start."
Frequently Asked Questions
Can I see the todo list as a file somewhere? No — todos are in-session state, not persisted to disk. The only way to save them is to ask Claude to write them out.
What's the difference between Claude Code todos and my own TODO comments in code?
Claude Code todos are task-tracking for the current session. Code TODO: comments are development notes in source. They're unrelated — Claude doesn't automatically track code TODO comments as session tasks.
Can I use todos to delegate to another Claude session? Not directly. But you can write the todo list to a file and reference that file in a new session — effectively passing the task state.
Does Claude always show todos for multi-step tasks? Not always. Shorter multi-step tasks may get done without showing a todo list. The visual todo panel appears when the task is complex enough that Claude explicitly creates one. You can always ask: "Show me your plan as a todo list first."
Related Guides
- Claude Code Plan Mode Deep Dive — Planning before executing
- Claude Code Complete Guide — Full reference
- Context Engineering for Claude — CLAUDE.md optimization
Go Deeper
Power Prompts 300 — $29 — Includes task orchestration prompts: how to structure long multi-day refactors, review-gate patterns, and session handoff templates.
30-day money-back guarantee. Instant download.