TaskCreate, TaskUpdate, TaskList, TaskGet: Complete Reference

Introduction

Claude Code includes four Task tools that enable programmatic task management within your development workflow. These tools let you create tasks, track their status, manage dependencies, and coordinate work across complex multi-step projects.

Unlike simple to-do lists, Claude Code's Task tools support dependency tracking between tasks, ownership assignment, and status workflows. This makes them suitable for breaking down large features into manageable pieces that can be completed in sequence or parallel.

The Four Task Tools

Quick Reference Table

TaskCreate

The TaskCreate tool creates a new task in the task system. Use it to define work items that need to be tracked, whether they represent features, bugs, or subtasks of a larger initiative.

Parameters

Example Usage

TaskCreate:
  subject: "Add email validation to signup form"
  description: |
    Implement client-side email validation for the signup form.

    Requirements:
    - Validate email format using regex
    - Show inline error message below input
    - Disable submit button until valid
    - Match existing form validation patterns

    File: src/components/SignupForm.tsx
  activeForm: "Implementing email validation"

Returns

TaskCreate returns the newly created task object with a unique taskId that you will use with other Task tools:

{
  "taskId": "task_abc123",
  "subject": "Add email validation to signup form",
  "status": "pending",
  "createdAt": "2025-01-28T10:30:00Z"
}

Best Practices for Task Creation

• Be specific in subjects: "Add email validation" is better than "Fix form"
• Include acceptance criteria: What does "done" look like?
• Reference files: Point to specific files that need modification
• Keep descriptions focused: One task should do one thing well
• Use activeForm meaningfully: It provides visual feedback during long operations

TaskGet

The TaskGet tool retrieves complete details about a specific task. Use it when you need the full description before starting work, or when you need to check a task's current status and dependencies.

Parameters

Example Usage

TaskGet:
  taskId: "task_abc123"

Returns

TaskGet returns the complete task object with all its properties:

{
  "taskId": "task_abc123",
  "subject": "Add email validation to signup form",
  "description": "Implement client-side email validation...",
  "status": "in_progress",
  "owner": "frontend-agent",
  "blocks": ["task_def456"],
  "blockedBy": [],
  "createdAt": "2025-01-28T10:30:00Z",
  "updatedAt": "2025-01-28T10:45:00Z"
}

Response Fields

When to Use TaskGet

• Before starting work: Read the full description to understand requirements
• Checking dependencies: See what tasks are blocking or blocked by this one
• Verifying status: Confirm a task is available before claiming it
• Reviewing ownership: See who is currently working on a task

TaskUpdate

The TaskUpdate tool modifies existing tasks. This is your primary tool for managing task lifecycle: claiming tasks, marking them complete, establishing dependencies, and updating details as requirements evolve.

Parameters

Common Operations

Claiming a Task

When an agent picks up a task to work on, they should claim ownership and update the status:

TaskUpdate:
  taskId: "task_abc123"
  owner: "frontend-agent"
  status: "in_progress"

Completing a Task

When work is finished, mark the task as completed. This automatically unblocks any dependent tasks:

TaskUpdate:
  taskId: "task_abc123"
  status: "completed"

Adding Dependencies

Establish that one task must complete before another can start:

# Task B cannot start until Task A completes
TaskUpdate:
  taskId: "task_B"
  addBlockedBy: ["task_A"]

# Equivalent: Task A blocks Task B
TaskUpdate:
  taskId: "task_A"
  addBlocks: ["task_B"]

Deleting a Task

Remove a task that is no longer needed. Use this for duplicate tasks, cancelled features, or tasks created in error:

TaskUpdate:
  taskId: "task_abc123"
  status: "deleted"

TaskList

The TaskList tool returns all tasks in the system with their current status, owners, and blocking relationships. Use it to get an overview of work in progress and identify available tasks.

Parameters

TaskList takes no parameters. It returns all tasks regardless of status.

TaskList

Returns

TaskList returns an array of task summaries. Note that descriptions are truncated; use TaskGet for full details:

{
  "tasks": [
    {
      "taskId": "task_abc123",
      "subject": "Add email validation to signup form",
      "status": "completed",
      "owner": "frontend-agent",
      "blockedBy": []
    },
    {
      "taskId": "task_def456",
      "subject": "Add password strength indicator",
      "status": "in_progress",
      "owner": "frontend-agent",
      "blockedBy": []
    },
    {
      "taskId": "task_ghi789",
      "subject": "Write signup form tests",
      "status": "pending",
      "owner": null,
      "blockedBy": ["task_abc123", "task_def456"]
    }
  ]
}

Understanding "Available" Tasks

A task is considered "available" to work on when:

• Status is pending (not yet started)
• The blockedBy array is empty (no pending dependencies)
• The owner is null (not claimed by another agent)

In the example above, only tasks with empty blockedBy arrays and pending status are ready to be claimed. Task task_ghi789 cannot start until both task_abc123 and task_def456 are completed.

Filtering Results

TaskList returns all tasks. To find specific subsets, filter the results in your code:

# Available tasks (pending + unblocked + unassigned)
available = [t for t in tasks
             if t.status == "pending"
             and len(t.blockedBy) == 0
             and t.owner is None]

# My tasks (assigned to me)
my_tasks = [t for t in tasks
            if t.owner == "my-agent-id"]

# Blocked tasks (waiting on dependencies)
blocked = [t for t in tasks
           if len(t.blockedBy) > 0]

Status Workflow

Tasks follow a straightforward lifecycle from creation to completion. Understanding this flow helps you manage work effectively.

Status Definitions

When to Use Each Status

• pending: Default for new tasks. Return tasks here if you need to pause work without abandoning it.
• in_progress: Always set when actively working. Signals to other agents that the task is claimed.
• completed: Set when all acceptance criteria are met. Triggers unblocking of dependent tasks.
• deleted: Use sparingly. Prefer completing tasks with notes if work was partially done.

Practical Examples

These examples demonstrate common patterns for using Task tools in real development workflows.

Creating a 3-Task Project

Break down a feature into sequential tasks with proper dependencies:

# Step 1: Create the first task (no dependencies)
TaskCreate:
  subject: "Create User model schema"
  description: |
    Define the User model with fields:
    - id (UUID)
    - email (string, unique)
    - passwordHash (string)
    - createdAt (timestamp)

    File: src/models/User.ts
  activeForm: "Creating User model"

# Returns: taskId = "task_001"

# Step 2: Create second task that depends on the first
TaskCreate:
  subject: "Implement UserService"
  description: |
    Create UserService with methods:
    - createUser(email, password)
    - getUserById(id)
    - getUserByEmail(email)

    File: src/services/UserService.ts
  activeForm: "Building UserService"

# Returns: taskId = "task_002"

TaskUpdate:
  taskId: "task_002"
  addBlockedBy: ["task_001"]

# Step 3: Create third task that depends on both
TaskCreate:
  subject: "Write User integration tests"
  description: |
    Test the full user creation and retrieval flow.

    File: tests/integration/user.test.ts
  activeForm: "Writing tests"

# Returns: taskId = "task_003"

TaskUpdate:
  taskId: "task_003"
  addBlockedBy: ["task_001", "task_002"]

Agent Workflow: Claim, Work, Complete

The typical pattern for an agent picking up and completing work:

# 1. Check available tasks
TaskList
# Response shows task_001 is pending with no blockers

# 2. Get full details before starting
TaskGet:
  taskId: "task_001"
# Response includes full description with requirements

# 3. Claim the task and start work
TaskUpdate:
  taskId: "task_001"
  owner: "backend-agent"
  status: "in_progress"

# 4. ... do the actual work ...

# 5. Mark complete when done
TaskUpdate:
  taskId: "task_001"
  status: "completed"

# 6. Check for newly available tasks
TaskList
# Response now shows task_002 is available (task_001 completed)

Handling Dependencies and Unblocking

When tasks complete, dependent tasks automatically become available:

# Initial state:
# - task_001: pending (no dependencies) <- AVAILABLE
# - task_002: pending (blocked by task_001)
# - task_003: pending (blocked by task_001, task_002)

# After completing task_001:
TaskUpdate:
  taskId: "task_001"
  status: "completed"

# New state:
# - task_001: completed
# - task_002: pending (no dependencies) <- NOW AVAILABLE
# - task_003: pending (blocked by task_002)

# After completing task_002:
TaskUpdate:
  taskId: "task_002"
  status: "completed"

# Final state:
# - task_001: completed
# - task_002: completed
# - task_003: pending (no dependencies) <- NOW AVAILABLE

Going Further

The Task tools are powerful primitives for managing work. They provide the building blocks for tracking dependencies, assigning ownership, and coordinating complex multi-step workflows within Claude Code sessions.

However, raw Task tools require significant manual coordination. You need to create tasks, establish dependencies, track which agent should handle what, and manage the entire workflow yourself. This works for simple projects but becomes cumbersome as complexity grows.

The Limitation of Manual Task Management

Using Task tools directly means you must:

• Manually break down every feature into tasks
• Remember to set up dependencies correctly
• Track which agent types handle which work
• Coordinate handoffs between tasks
• Handle edge cases when tasks fail or need revision

This overhead is manageable for small projects, but scales poorly. A 10-task feature requires careful coordination; a 50-task project becomes a full-time job just managing the task system.

Structured Agent Teams: The Better Approach

Instead of manually orchestrating tasks, Claude Architect provides pre-configured agent teams with built-in coordination. You describe what you want to build; the system handles task decomposition, agent assignment, and dependency management automatically.

Think of it as the difference between writing assembly code and using a high-level language. Task tools are the assembly; structured agent teams are the abstraction that makes you productive.