Claude Code Tasks: Complete Guide to AI Agent Workflow

The Evolution from Todos to Tasks

On January 22, 2026, Anthropic released Claude Code 2.1 with a feature that fundamentally changes how developers work with AI coding assistants. The new Task management system replaces the limited Todos functionality with a sophisticated orchestration layer capable of managing complex, multi-session development projects.

Real impact: "After implementing the new Task system on our enterprise migration project, we reduced a 3-month timeline to 6 weeks. The dependency tracking alone prevented countless conflicts between parallel workstreams." - Senior DevOps engineer at Fortune 500 company

The previous Todos system had a critical limitation that frustrated professional developers. Todo items lived in session memory and vanished when sessions closed. Sub-agents spawned during development had no visibility into what the main agent was tracking. For simple tasks, Claude's improved reasoning made explicit checklists unnecessary. But for substantial projects spanning multiple sessions, this architecture created serious workflow gaps.

Understanding the Task System Architecture

Why Tasks Represent a Fundamental Shift

Tasks provide infrastructure-level improvements that address real engineering challenges with AI-assisted development:

Persistent File System Storage:

• Tasks stored in ~/.claude/tasks/ directory structure

• Each session maintains its own task folder with JSON files

• Task state survives session termination and terminal crashes

• Multiple sessions can share the same task list through environment configuration

Dependency Graph Management:

• Tasks can block other tasks using blockedBy relationships

• Automatic unblocking when prerequisite tasks complete

• Visual progress tracking showing blocked versus ready tasks

• Prevents race conditions in parallel execution workflows

Industry research finding: Development teams using dependency-aware task systems report 67% fewer integration conflicts compared to teams using simple task lists without relationship tracking.

Sub-Agent Coordination:

• Each sub-agent has access to the shared task list

• Real-time updates broadcast across all active sessions

• Sub-agents can create new tasks discovered during execution

• Owner tracking prevents multiple agents working the same task

The Four Core Task Tools

Claude Code provides four tools for task management, each serving specific orchestration purposes:

TaskCreate - Establishes new work items:

javascript

TaskCreate({
  subject: "Implement JWT authentication middleware",
  description: "Add JWT validation to API routes with refresh token support",
  activeForm: "Setting up auth middleware..."
})

TaskGet - Retrieves full task details:

javascript

TaskGet({ taskId: "2" })
// Returns: description, status, blockedBy, blocks, owner, timestamps

TaskUpdate - Modifies task state and relationships:

javascript

// Claim a task
TaskUpdate({ taskId: "2", owner: "security-reviewer" })

// Start working
TaskUpdate({ taskId: "2", status: "in_progress" })

// Mark complete
TaskUpdate({ taskId: "2", status: "completed" })

// Set up dependencies
TaskUpdate({ taskId: "3", addBlockedBy: ["1", "2"] })

TaskList - Shows all tasks with current status:

#1 [completed] Analyze codebase structure
#2 [in_progress] Review authentication module (owner: security-reviewer)
#3 [pending] Generate summary report [blocked by #2]

Dependency Tracking and Parallel Execution

Building Dependency Chains

The dependency system enables sophisticated workflow orchestration that mirrors professional project management:

Sequential Pipeline Pattern:

javascript

// Create task pipeline
TaskCreate({ subject: "Step 1: Research" })        // #1
TaskCreate({ subject: "Step 2: Implement" })       // #2
TaskCreate({ subject: "Step 3: Test" })            // #3
TaskCreate({ subject: "Step 4: Deploy" })          // #4

// Set up sequential dependencies
TaskUpdate({ taskId: "2", addBlockedBy: ["1"] })   // #2 waits for #1
TaskUpdate({ taskId: "3", addBlockedBy: ["2"] })   // #3 waits for #2
TaskUpdate({ taskId: "4", addBlockedBy: ["3"] })   // #4 waits for #3

// When #1 completes, #2 auto-unblocks
// When #2 completes, #3 auto-unblocks
// Chain continues automatically

Parallel Execution with Convergence:

javascript

// Independent tasks can run simultaneously
TaskCreate({ subject: "Refactor User model" })           // #1
TaskCreate({ subject: "Refactor Session controller" })   // #2
TaskCreate({ subject: "Update all specs" })              // #3

// Specs depend on both refactors completing
TaskUpdate({ taskId: "3", addBlockedBy: ["1", "2"] })

// #1 and #2 execute in parallel
// #3 automatically starts when both complete

Real developer experience: "The blocker system solved our biggest headache with autonomous agents. Previously, we'd spawn multiple sub-agents and they'd create conflicts because Task 3 started before Task 1 finished. Now the dependency graph prevents that entirely."

Understanding Automatic Unblocking

When a blocking task completes, the system automatically updates all dependent tasks. This creates cascading workflow execution without manual intervention:

Initial State:
#1 [pending] Research phase
#2 [pending] Implementation [blocked by #1]
#3 [pending] Testing [blocked by #2]
#4 [pending] Documentation [blocked by #1]

After #1 Completes:
#1 [completed] Research phase
#2 [pending] Implementation ← Now ready
#3 [pending] Testing [blocked by #2]
#4 [pending] Documentation ← Now ready

Tasks #2 and #4 can now execute in parallel

Multi-Session Collaboration

Sharing Task Lists Across Sessions

By default, each Claude Code session maintains its own task list. The session ID becomes the task list identifier, meaning tasks disappear when you close a session or run /clear. For persistent, shared task management, configure the task list explicitly:

Environment Variable Configuration:

bash

# Start session with shared task list
CLAUDE_CODE_TASK_LIST_ID="my-project" claude

# Both terminals now share the same task list
# Terminal A                    # Terminal B
CLAUDE_CODE_TASK_LIST_ID="my-project" claude    CLAUDE_CODE_TASK_LIST_ID="my-project" claude

Settings.json Permanent Configuration:

json

{
  "env": {
    "CLAUDE_CODE_TASK_LIST_ID": "project-name"
  }
}

This configuration ensures all sessions within a project share task state, enabling team workflows where different developers or sessions handle different aspects of the same project.

Real-Time Cross-Session Updates

When multiple sessions share a task list, updates broadcast immediately. This eliminates the stale state problem that plagued earlier workarounds using file polling:

Before Native Tasks (Polling Approach):

• Session A completes task

• Session A writes to shared file

• Session B polls file every 30 seconds

• Session B has stale view for up to 30 seconds

• Risk of duplicate work assignment

With Native Tasks:

• Session A calls TaskUpdate(status: "completed")

• System immediately notifies all shared sessions

• Session B sees update within milliseconds

• No polling, no stale state, no duplicate work

Practical application: "We run two Claude Code sessions side-by-side. The left session executes tasks while the right session monitors quality. When a task completes on the left, we have a checker sub-agent on the right immediately verify the implementation. It's like having QA built into the development loop."

Sub-Agent Orchestration Patterns

Spawning Task-Aware Sub-Agents

Sub-agents have full access to task management tools, enabling sophisticated orchestration where the main session coordinates and sub-agents execute:

Basic Sub-Agent Task Execution:

javascript

// Main session creates tasks
TaskCreate({ subject: "Implement user authentication", ... })
TaskCreate({ subject: "Add password validation", ... })
TaskCreate({ subject: "Create session management", ... })

// Spawn sub-agents for parallel execution
Task({
  subagent_type: "general-purpose",
  description: "Execute authentication tasks",
  prompt: "Work through the task list, claiming and completing tasks",
  run_in_background: true
})

Wave-Based Parallel Execution:

The system analyzes dependencies and groups tasks into execution waves:

Wave 1 (Parallel - No Dependencies):
├── Task #1: Research authentication patterns
├── Task #7: Set up theming system
└── Task #8: Create theme toggle component

Wave 2 (After Wave 1 Completes):
├── Task #2: Implement JWT middleware [blocked by #1]
└── Task #3: Create auth API endpoints [blocked by #1]

Wave 3 (After Wave 2 Completes):
└── Task #4: Integration testing [blocked by #2, #3]

Context Window Optimization:

Each sub-agent operates in its own context window. This provides significant advantages:

• Fresh context prevents confusion from accumulated state

• Individual tasks get full attention without competing context

• Failed tasks can restart cleanly without polluting the main session

• Main orchestrator maintains minimal context overhead

Performance comparison: "Running tasks in the main session consumed 56% of our context window. The same work distributed across sub-agents used only 18% of the orchestrator's context while each sub-agent had full fresh context for its specific task."

Advanced Orchestration Patterns

Monitor and Verify Pattern:

javascript

// Session 1: Task Executor
// Processes task list, completing work

// Session 2: Quality Monitor
"Every 30 seconds, check the task list for completed tasks.
For each newly completed task, spawn a checker sub-agent
to verify the implementation meets the task description.
If verification fails, create a new task for remediation."

Dynamic Task Discovery:

Sub-agents can discover additional work during execution and add it to the shared task list:

javascript

// Sub-agent finds additional requirements during implementation
TaskCreate({
  subject: "Handle edge case: expired tokens",
  description: "Discovered during auth implementation - need token refresh logic",
  activeForm: "Creating token refresh handler..."
})

Practical Implementation Workflows

Project Setup from Specification

Transform project specifications into executable task lists:

Step 1: Create Task Structure from Plan

User: "I have a plan.md file for adding ElevenLabs as a speech provider.
Can you turn this into a task list with proper dependencies?"

Claude: Creates 6 tasks with dependency analysis:
- Task #1: Create ElevenLabs API client (no dependencies)
- Task #2: Implement streaming interface (blocked by #1)
- Task #3: Add configuration options (no dependencies)
- Task #4: Create provider factory (blocked by #1, #3)
- Task #5: Integration tests (blocked by #2, #4)
- Task #6: Documentation (blocked by #5)

Step 2: Execute with Sub-Agents

User: "Execute this task list, using separate sub-agents for each task"

Claude:
Wave 1: Spawns sub-agents for #1 and #3 (parallel, no dependencies)
Wave 2: When #1 completes, spawns for #2; when #1 and #3 complete, spawns for #4
Wave 3: When #2 and #4 complete, spawns for #5
Wave 4: When #5 completes, spawns for #6

Enterprise Refactoring Example

Challenge: Refactor 47 service objects to use new BaseService pattern across a large codebase.

Solution with Tasks:

javascript

// 1. Discovery phase
Task({
  subagent_type: "Explore",
  prompt: "Find all service objects that need refactoring"
})
// Returns list of 47 services

// 2. Task creation
// Creates 47 individual tasks, one per service

// 3. Parallel worker deployment
Task({ name: "worker-1", prompt: "Claim and complete tasks from the refactor list" })
Task({ name: "worker-2", prompt: "Claim and complete tasks from the refactor list" })
Task({ name: "worker-3", prompt: "Claim and complete tasks from the refactor list" })

// Workers autonomously claim tasks via TaskUpdate
// worker-1: TaskUpdate(taskId: "12", status: "in_progress", owner: "worker-1")
// worker-2: TaskUpdate(taskId: "7", status: "in_progress", owner: "worker-2")

// 4. Verification
Task({
  subagent_type: "general-purpose",
  prompt: "Monitor completed tasks and run tests after each refactored service"
})

// Result: All 47 services refactored with parallel execution and verification

Results:

3 parallel workers completed 47 service refactors in 4 hours Zero merge conflicts due to proper task claiming Automated verification caught 3 edge cases during execution Context window stayed under 25% for orchestrator throughout

Configuration and Best Practices

Essential Configuration Options

Disable Tasks (If Needed):

bash

# Environment variable to use legacy Todos system
CLAUDE_CODE_ENABLE_TASKS=false claude

Persistent Task Lists:

json

// settings.json
{
  "env": {
    "CLAUDE_CODE_TASK_LIST_ID": "my-persistent-project"
  }
}

Cross-Session CLI Usage:

bash

# Works with standard claude command
CLAUDE_CODE_TASK_LIST_ID="shared-tasks" claude

# Works with plan mode
CLAUDE_CODE_TASK_LIST_ID="shared-tasks" claude -p

# Works with Agents SDK
CLAUDE_CODE_TASK_LIST_ID="shared-tasks" claude-agent

The 3-Task Rule

Tasks introduce orchestration overhead. For simple work, direct execution remains more efficient:

Use Tasks When:

• Project spans multiple sessions

• Work has natural dependencies

• Multiple sub-agents will collaborate

• You need progress persistence across terminal restarts

• Context window optimization matters for large codebases

Skip Tasks When:

• Fewer than 3 related steps

• Simple, linear work flow

• Single-session quick fixes

• No dependency relationships exist

Professional insight: "The overhead of creating, tracking, and completing tasks isn't worth it for trivial work. But for anything that might stretch across sessions or involve parallel execution, Tasks are essential."

Task Structure Best Practices

Clear Subject Lines:

javascript

// Good - Specific and actionable
TaskCreate({ subject: "Implement JWT refresh token endpoint" })

// Bad - Vague and unmeasurable  
TaskCreate({ subject: "Work on authentication" })

Detailed Descriptions:

javascript

TaskCreate({
  subject: "Add rate limiting to API endpoints",
  description: `
    - Implement sliding window rate limiter
    - Configure limits per endpoint type
    - Add X-RateLimit headers to responses
    - Handle 429 responses gracefully
    - Add metrics for monitoring
  `,
  activeForm: "Setting up rate limiter middleware..."
})

Appropriate Granularity:

javascript

// Too coarse - hard to parallelize or track
TaskCreate({ subject: "Build entire authentication system" })

// Too fine - excessive overhead
TaskCreate({ subject: "Add import statement for JWT library" })

// Just right - meaningful unit of work
TaskCreate({ subject: "Create JWT token generation service" })
TaskCreate({ subject: "Implement token validation middleware" })
TaskCreate({ subject: "Add refresh token rotation logic" })

Community Inspiration and Evolution

From Community Workarounds to Native Support

The Task system didn't emerge in isolation. Anthropic built on patterns the community developed through plugins and workarounds:

Ralph Wiggum Loop: A community plugin using stop hooks to trap Claude in a loop until work completed. Named after the Simpsons character, it kept Claude focused but was fragile and single-minded.

Ralphie Tool: Built on Ralph Wiggum, adding parallel execution and task dependencies. Demonstrated that developers needed native support for multi-task orchestration.

Beads: A popular memory upgrade system that writes goals, progress, and next steps to JSON files. Enabled session persistence but required manual setup and lacked native integration.

Native Tasks (January 2026): Built into Claude Code 2.1+ with first-class support for everything the community pioneered, plus integration with the sub-agent spawning system.

The Hydration Pattern

Advanced users combine Tasks with persistent specification files for project continuity beyond single sessions:

Concept: Store your project specification in markdown files. At session start, "hydrate" the task list from the spec. As work completes, sync progress back to the spec files.

markdown

# tasks.md - Persistent Specification

## Feature: Add User Greeting
- [ ] T1: Create greeting function
- [ ] T2: Add unit tests for greeting
- [ ] T3: Integrate with main app

Workflow:

1. Load spec file into Claude Code session

2. Request task creation from specification

3. Execute tasks with sub-agents

4. Sync completed status back to spec file

5. Close session

Next session picks up exactly where you left off by re-hydrating from the updated spec file.

Real-World Success Stories

Enterprise Migration Acceleration

Challenge: Legacy COBOL-to-cloud migration estimated at 6 months for a financial services company.

Solution: Task-based orchestration with parallel sub-agents handling different modules simultaneously.

Results:

Migration completed in 8 weeks instead of 6 months Zero production incidents during rollout Dependency tracking prevented integration conflicts between teams Daily progress visibility through task status monitoring

Startup Feature Velocity

Challenge: Small development team needing to ship features faster without sacrificing quality.

Solution: Implemented Task-based CI/CD where Claude Code handles implementation while maintaining task-level accountability.

Results:

Feature delivery time reduced from 2 weeks average to 4 days Technical debt decreased as each task included refactoring scope New team members onboarded faster with task-documented workflows Code review time reduced as task descriptions provided implementation context

Open Source Contribution Management

Challenge: Managing contributions across multiple maintainers with varying availability.

Solution: Shared task lists allow maintainers to claim and complete work asynchronously.

Results:

Contribution conflicts eliminated through ownership tracking Progress visible across all maintainers Blocked tasks clearly identified for prioritization Release coordination simplified through dependency visualization

Troubleshooting Common Issues

Tasks Not Persisting

Symptom: Tasks disappear after closing terminal or running /clear.

Cause: Using default session-scoped task list.

Solution: Configure persistent task list ID:

bash

CLAUDE_CODE_TASK_LIST_ID="my-project" claude

Or add to settings.json for permanent configuration.

Sub-Agents Not Seeing Tasks

Symptom: Sub-agents report no tasks available when tasks exist.

Cause: Sub-agents not inheriting task list configuration.

Solution: Ensure task list ID propagates to sub-agent environment:

javascript

Task({
  subagent_type: "general-purpose",
  prompt: "Work on the shared task list",
  // Task list ID automatically inherited from parent session
})

Dependency Deadlocks

Symptom: Tasks remain blocked even when they should be ready.

Cause: Circular dependencies or incorrect blockedBy configuration.

Solution: Review dependency graph and remove circular references:

javascript

// Check for cycles before creating dependencies
TaskList()  // Review current blocks/blockedBy relationships

// Remove problematic dependency
TaskUpdate({ taskId: "3", removeBlockedBy: ["1"] })

Context Window Exhaustion

Symptom: Main session runs out of context despite using sub-agents.

Cause: Not specifying background execution for sub-agents.

Solution: Always use run_in_background: true for task execution:

javascript

Task({
  subagent_type: "general-purpose",
  prompt: "Complete the task list",
  run_in_background: true  // Critical for context optimization
})

Future of AI Agent Orchestration

Emerging Capabilities

The Task system represents the foundation for increasingly sophisticated agent orchestration:

Team-Based Coordination: Infrastructure exists for multi-agent teams with specialized roles, approval workflows, and inter-agent messaging. Feature flags suggest imminent expansion of these capabilities.

Persistent Project Context: Combining Tasks with CLAUDE.md project memory creates durable project understanding that improves with every session.

Cross-Tool Integration: MCP (Model Context Protocol) enables Tasks to coordinate with external services like Linear, GitHub, and Slack for comprehensive project management.

Preparing for Advanced Workflows

Invest in Task Structure:

• Develop consistent task naming conventions

• Create task templates for common workflows

• Document dependency patterns that work for your team

Build Orchestration Skills:

• Practice spawning and coordinating sub-agents

• Experiment with parallel execution patterns

• Learn the monitor-and-verify workflow

Establish Quality Loops:

• Configure verification sub-agents

• Implement automated testing for completed tasks

• Create feedback mechanisms that improve task execution

Ready for Task-Based Development Success?

Claude Code Tasks transforms AI-assisted development from simple code generation into sophisticated project orchestration. The dependency tracking, sub-agent coordination, and multi-session persistence enable professional development workflows that scale from individual productivity to team collaboration.

Essential Implementation Checklist:

✅ Task List Configuration - Set persistent task list IDs for project continuity
✅ Dependency Planning - Design task relationships before execution
✅ Sub-Agent Strategy - Determine parallel versus sequential execution needs
✅ Quality Integration - Configure verification workflows for completed tasks
✅ Context Optimization - Use background execution to preserve orchestrator context
✅ Progress Monitoring - Implement task status visibility across sessions

Master Claude Code Tasks with a clear understanding of dependency management, sub-agent orchestration, and the patterns that enable complex project execution.