Claude Code Tasks

Problem: Autonomous Claude Code loops used to need Ralph Wiggum hacks. External plan files, stop hooks, and completion promises kept long runs alive. It worked. It also needed a lot of duct tape to hold context across sessions.

Quick Win: Anthropic shipped task management as a first-class feature. Spin up persistent tasks with dependencies:

claude "add user authentication - break into tasks with dependencies"

Hit Ctrl+T to show the task list in your terminal. Tasks stay alive between sessions. You never have to re-explain what you were doing.

Tasks: Todos, Upgraded

Anthropic rolled out the new task system on January 23, 2025. What used to be flat checklists is now a project tracker with dependencies, blockers, and live sync across sessions.

The previous TodoWrite tool held a simple list in memory. Today's system splits the job across four dedicated tools:

What Changes

Old behavior: todos lived in Claude's memory and died on context reset. New behavior: tasks are stored at ~/.claude/tasks/ inside your home directory (not inside the repo) and updates go out to every open session.

The old todo lessons still hold up. Tasks are only as good as your instructions, and any mismatch points straight at a briefing gap. The new piece is everything underneath: persistence and dependencies built into the tool.

Tasks vs Ralph Wiggum: What Changes

Ralph Wiggum got there first. It kept Claude Code grinding overnight with stop hooks, plan files on disk, and a prompt that promised completion. The recipe worked. It also leaned hard on workarounds.

Those workarounds now have native replacements:

The same core lesson still holds: verification is what carries the whole thing. Ralph showed us that Claude needs a hard rule for what "done" means. Native tasks keep that idea and move the wiring into the tool itself.

Still running Ralph loops? You don't have to rip them out. Tasks simply hand you the primitives the community has been stitching together. Anthropic watched what developers were doing and made it native.

Task Dependencies and Blockers

Dependencies are where tasks get interesting. A task can block another task:

Task 1: Design database schema
Task 2: Create API endpoints (blocked by Task 1)
Task 3: Build frontend components (blocked by Task 2)

Claude handles the bookkeeping. Finish Task 1 and Task 2 unlocks on its own. Parallel work stops tripping over itself.

Creating Dependent Tasks

When Claude splits a big job into pieces, it wires the dependency chain as it goes:

TaskCreate(subject="Design auth schema", description="...")
TaskCreate(subject="Implement auth API", description="...")
TaskUpdate(taskId="2", addBlockedBy=["1"])

Chaining happens through the addBlockedBy parameter. Its opposite, addBlocks, lets you say what a task is blocking instead.

Multi-Session Collaboration

Here the tool earns its keep. An environment variable lets more than one session share the same task list:

CLAUDE_CODE_TASK_LIST_ID=my-project claude

Now every Claude session pointed at that ID works from the same list. Finish a task in Session A and Session B sees the update right away. You get:

• Parallel workstreams: Frontend and backend sessions sharing blockers
• Resume anywhere: Close your laptop, open it tomorrow, tasks are exactly where you left them
• Team coordination: Multiple developers sharing task state

Practical Multi-Session Workflow

1. Open your main session and give the task list a name:

CLAUDE_CODE_TASK_LIST_ID=feature-auth claude 2. Break the work into tasks and set dependencies

3. Open a second session using the same ID for parallel work:

CLAUDE_CODE_TASK_LIST_ID=feature-auth claude # Same ID 4. Both sessions see and update the shared task list

The Agent SDK respects the same list, so subagents can pick up and finish tasks alongside you.

Task Status Lifecycle

pending → in_progress → completed

Flip a task to in_progress the moment you start on it. A spinner appears in the task list, and any other sessions know that work is underway. Only move it to completed once the work is actually done.

Tasks survive context compactions. Even in long-running sessions where Claude's memory gets squeezed, the task state is still there.

Keyboard Shortcuts

Ctrl+T opens and closes the task list inside the terminal. What you see:

• Pending tasks (up to 10 at a time)
• In-progress tasks with spinner
• Completed tasks with checkmark

You can also tell Claude "show me all tasks" or "clear all tasks" if you want to drive it with plain language.

When to Use Tasks

Reach for tasks on the hard jobs. A simple ask doesn't need any of this.

Use Tasks when:

• Multi-step implementation with dependencies
• Work spanning multiple sessions
• Parallel subagent coordination
• Projects where you'll pause and resume

Skip Tasks when:

• Single-file changes
• Quick questions
• One-shot commands

Configuring Task Behavior

Drop task rules into your CLAUDE.md file:

## Task Management
 
- Use TaskCreate for multi-step work
- Set dependencies with addBlockedBy for sequential phases
- Update status to in_progress before starting each task
- Mark completed only after verification

For projects that span sessions, you can put the environment variable in your shell profile too:

# In .bashrc or .zshrc
export CLAUDE_CODE_TASK_LIST_ID=my-project

Migration from Todos

Still have TodoWrite rules in your config? Rewrite them:

Old approach:

Keep session checklists in TodoWrite

New approach:

Use TaskCreate for each checklist item
Update status via TaskUpdate (pending → in_progress → completed)
Set dependencies with addBlockedBy parameter

The /todos command is still around as an alias. Behind it, the engine is now Tasks.

Remember: Ralph taught us the idea. Tasks make it native. Keep the verification discipline, let the tool handle the plumbing, and retire the hand-rolled state files.