DEV Community

Sangmin Lee
Sangmin Lee

Posted on • Originally published at claudeguide.io

The Todo System in Claude Code: When and How to Use It

#todo #workflow

Originally published at claudeguide.io/claude-code-todo-system

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 in 2026. 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:

  1. The task has 4+ distinct steps — "Add auth, update the API, add tests, update docs"
  2. Steps have dependencies — Step B requires Step A to be done first
  3. The task will take many tool calls — Reading multiple files, running multiple commands
  4. 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"
Enter fullscreen mode Exit fullscreen mode

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."
Enter fullscreen mode Exit fullscreen mode

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?
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

Reprioritizing 

# Stop current work and shift focus
"Put the CLAUDE.md update last — focus on the database migrations first"
Enter fullscreen mode Exit fullscreen mode

Checking status 

# Ask what's left
"What's still on the list?"
Enter fullscreen mode Exit fullscreen mode

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."
Enter fullscreen mode Exit fullscreen mode

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."
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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."
Enter fullscreen mode Exit fullscreen mode

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:

  1. End each session with a status update: "Summarize what we completed and what's left"
  2. 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."
Enter fullscreen mode Exit fullscreen mode
  1. 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."
Enter fullscreen mode Exit fullscreen mode

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

Go Deeper

Power Prompts 300 — $29 — Includes task orchestration prompts: how to structure long multi-day refactors, review-gate patterns, and session handoff templates.

→ Get Power Prompts 300 — $29

30-day money-back guarantee. Instant download.

Top comments (0)