How Claude Task Works and How to Use It | From Task Creation to Parallel Execution

What Is Claude Task — A New System for Tracking Progress

According to Anthropic's official Task documentation, Claude Code uses the Task system to organize complex work and show progress to users as it proceeds. Starting with Claude Code v2.1.142, the legacy TodoWrite tool has been deprecated and its responsibilities split into four tools: TaskCreate, TaskUpdate, TaskGet, and TaskList.

Situations where Tasks are automatically created:

• Complex multi-step work with 3 or more steps
• When a user lists multiple items in a single request
• When the user explicitly says "show me progress as you go"
• Non-trivial operations where making progress visible to the user is beneficial

The task lifecycle progresses in order: pending → in_progress → completed. Once all tasks are complete, the list is automatically cleared. To delete a task manually, use TaskUpdate with status: "deleted".

TaskCreate — The Key Is Creating Tasks One at a Time

The old TodoWrite was designed to batch-rewrite multiple todos as an array, but TaskCreate is a single-item operation that creates one task at a time.

TaskCreate(
  subject: "Add unit tests for the authentication module",
  description: "Cover the 3 flows: login / logout / refresh",
  activeForm: "Writing tests…"
)

Parameter overview:

• subject (required): The task title
• description: A detailed description
• activeForm: Dynamic text displayed while the task is in_progress
• metadata: Optional additional information

The response to a TaskCreate call includes a task_id. This ID is the key for subsequent TaskUpdate / TaskGet calls. If you are monitoring externally via the SDK, extract and store the ID from the { "task": { "id": "...", "subject": "..." } } structure in the tool_result block.

TaskUpdate — Fine-Grained Status Control

TaskUpdate updates a specific task individually by specifying its taskId. Simply set it to in_progress when work begins and completed when done, and progress will be reflected on the user's screen.

TaskUpdate(taskId: "abc123", status: "in_progress")
# ...actual work...
TaskUpdate(taskId: "abc123", status: "completed")

Fields that can be modified:

• status: pending / in_progress / completed / deleted
• subject, description, activeForm: Content edits
• addBlocks: Adding dependent tasks
• addBlockedBy: Setting upstream task dependencies
• owner: Changing task ownership (effective in Agent Teams)

TaskGet and TaskList — Understanding the Current State

TaskGet retrieves the latest snapshot of a single task by specifying its taskId. TaskList returns all tasks or a filtered subset using the filter parameter.

# Check incomplete tasks
TaskList(filter: "in_progress")

# Check the status of a specific task
TaskGet(taskId: "abc123")

This is commonly used when a session is interrupted mid-work and Claude itself calls TaskList to understand what remains. It is also useful if you want to build a progress dashboard in external code by capturing TaskList tool_result events from the stream.

TaskStop and TaskOutput — Managing Background Sessions

TaskStop and TaskOutput are tools for controlling Claude Code sessions running in the background.

• TaskOutput: Retrieves the current output of an active background session
• TaskStop: Safely stops a session (waits for the current request or tool call to complete before stopping)

The agent view (launched with claude agents) is an interface that lists multiple background sessions in three states: "Needs input / Working / Completed." A typical use case is offloading long-running tasks like refactoring or CI analysis to the background while working on something else in parallel.

Shared Task Lists in Agent Teams

Agent Teams (Claude Code v2.1.32 and later, experimental) allow multiple Claude Code instances to coordinate via a shared task list.

How to enable:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

How it works:

1. The team leader creates a task list
2. Team members autonomously claim tasks
3. File locking prevents double-claiming
4. Tasks with dependencies wait until prerequisite tasks are complete

A typical prompt:

Please review PR #42 from 3 perspectives:
- Security: focus on authentication, session management, and input validation
- Performance: focus on DB queries and API latency
- Testing: focus on coverage and test quality

With a single prompt like this, 3 sessions launch in parallel, each independently claiming and executing their tasks. After completion, the leader consolidates the three sets of findings.

Quality gates can also be configured via hooks:

• TeammateIdle: Runs before a team member goes idle
• TaskCreated: Validates on task creation; exit 2 blocks creation
• TaskCompleted: Validates before marking complete; exit 2 blocks completion

Monitoring Task State via the Python / TypeScript SDK

When programmatically controlling Claude Code via the SDK, you can retrieve task progress in real time by reading the tool_use blocks in the assistant's stream.

from claude_agent_sdk import query, AssistantMessage, ToolUseBlock

async for message in query(prompt="Optimize the performance of a React app"):
    if not isinstance(message, AssistantMessage):
        continue
    for block in message.content:
        if not isinstance(block, ToolUseBlock):
            continue
        if block.name == "TaskCreate":
            print(f"📋 Created: {block.input['subject']}")
        elif block.name == "TaskUpdate":
            status = block.input.get("status", "")
            icon = "✅" if status == "completed" else "🔧" if status == "in_progress" else "⏳"
            print(f"{icon} Updated: {block.input['taskId']} → {status}")

The task_id is obtained from the tool_result of TaskCreate. The input to TaskCreate does not contain a task_id. It is returned as the corresponding tool_result block in the form { "task": { "id": "...", "subject": "..." } }, so accumulate these in a map.

The official Todo Tracking guide includes sample code for both TypeScript and Python.

Comparison with TodoWrite and Migration Points

The switch to Task tools is enabled by default in TypeScript Agent SDK 0.3.142 / Claude Code v2.1.142. If you need the legacy TodoWrite behavior, you can revert with CLAUDE_CODE_ENABLE_TASKS=0.

Detailed migration steps in Python are covered in "Claude Agent SDK Python | TodoWrite Deprecation and Migration to Task Tools."

Common Practical Patterns

Large-Scale Refactoring

For refactoring spanning multiple files, Claude Code automatically creates per-file tasks and tracks progress with in_progress → completed. Even if the session is interrupted mid-way, you can resume by checking remaining tasks with TaskList.

Integration into CI/CD Pipelines

With GitHub Actions integration, automated code reviews are run per PR and each checklist item is tracked as a Task. Security, performance, and test coverage are reviewed in parallel, and the review results are posted as comments on the PR.

Parallel Debugging via Competing Hypotheses

When the root cause of a bug is unknown, this approach involves forming multiple hypotheses and investigating each independently in separate sessions. Using Agent Teams' shared task list, each session claims its assigned hypothesis and verifies it independently. Parallel hypothesis testing helps mitigate confirmation bias that tends to arise when investigating with a single session.