TodoWrite vs Tasks API

v2.1.233: on Opus 4.8, Sonnet 5, Fable 5, Mythos 5, and newer models, both TodoWrite AND the Tasks API are disabled by default. Re-enable with CLAUDE_CODE_ENABLE_TODO_TOOLS=1.

Direct comparison

When to stay on TodoWrite

TodoWrite remains relevant for simple cases: a linear list that wraps up in under ten minutes, with no complex dependencies, in a single continuous session. The Tasks API setup represents an investment that only pays off if the project extends over time.

When to migrate to Tasks API

Work across multiple sessions    → Tasks API required
Dependencies between tasks       → native blockedBy
Multi-terminal or multi-agents   → real-time broadcast
Resume after /compact            → guaranteed persistence

Enable and disable

# Enable task tools on newer models
CLAUDE_CODE_ENABLE_TODO_TOOLS=1 claude

# Force fallback to TodoWrite (rare)
CLAUDE_CODE_ENABLE_TODO_TOOLS=1 CLAUDE_CODE_ENABLE_TASKS=0 claude

# Check current configuration
env | grep CLAUDE_CODE_ENABLE_TASKS

Migrating an existing TodoWrite list

Here is a typical transformation from a flat list to a Tasks API hierarchy.

Before (TodoWrite):

- [ ] Add user authentication
- [ ] Hash passwords
- [ ] Write tests

After (Tasks API):

export CLAUDE_CODE_TASK_LIST_ID="my-project-auth"
# Then inside Claude:
# TaskCreate parent + children with blockedBy

Update CLAUDE.md

When you migrate, update your project instructions so Claude automatically uses the right system. Specifying the expected list ID in CLAUDE.md prevents it from being forgotten between sessions.

Note on the future of TodoWrite

TodoWrite will continue to work, but Anthropic’s direction is clearly toward the Tasks API. New multi-agent coordination features are built exclusively on the Tasks API. Migrating now avoids a forced refactor later, on larger projects.

Automatic activation

The Tasks API became the default task system in v2.1.142. From v2.1.233, newer models disable both systems unless CLAUDE_CODE_ENABLE_TODO_TOOLS=1 is set. After opting in, CLAUDE_CODE_ENABLE_TASKS=0 selects legacy TodoWrite.