Designing Complex Project Orchestration with Claude Code Tasks: A Deep Dive

Claude Code Tasks Overview

Claude Code now includes a file‑based Task management system that supersedes the earlier Todos. Tasks are small JSON units stored on disk, can reference each other, and are visible to any Claude Code session or sub‑agent that shares the same task list.

Why Todos are insufficient

Todos exist only in the current session’s memory and disappear when the session ends.

Sub‑agents launched from the main session cannot see or modify those Todos.

Long‑running, multi‑session projects quickly run out of the flat, volatile Todo list.

Three core improvements introduced by Tasks

Persistent storage : each task is saved as a JSON file under ~/.claude/tasks, surviving session termination.

Dependency management : tasks can declare blocks and blockedBy arrays, enabling a directed acyclic graph of work.

Multi‑session collaboration : setting the environment variable CLAUDE_CODE_TASK_LIST_ID=name makes every Claude Code instance use the same task list, automatically propagating status changes.

File storage layout

~/.claude/tasks/
└── <uuid-folder>/
    ├── 1.json
    ├── 2.json
    └── ...

Each <uuid-folder> is a directory named with a UUID that groups the JSON files belonging to a single logical task list.

Task JSON schema

{
  "id": "1",
  "subject": "Initialize project and install dependencies",
  "description": "Set up project structure, package.json, and install core dependencies (express, dotenv, cors, etc.)",
  "activeForm": "Initializing project",
  "status": "pending",
  "blocks": ["2"],
  "blockedBy": []
}

Key fields:

id – unique identifier within the list.

subject – short title.

description – detailed work to be done.

activeForm – human‑readable status shown while the task is in progress.

status – one of pending, in_progress, completed.

blocks – IDs of tasks that must wait for this task to finish.

blockedBy – IDs of tasks that must finish before this task can start.

Task management commands

TaskCreate – creates a new task.

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

TaskGet – retrieves a task’s metadata.

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

TaskUpdate – modifies status, owner, or dependencies.

// Claim task
TaskUpdate({taskId: "2", owner: "security-reviewer"})
// Start work
TaskUpdate({taskId: "2", status: "in_progress"})
// Mark completed
TaskUpdate({taskId: "2", status: "completed"})
// Add dependencies
TaskUpdate({taskId: "3", addBlockedBy: ["1", "2"]})

TaskList – prints a concise view of all tasks.

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

Tasks vs. Todos

Todos are flat, in‑memory lists that vanish after a session ends. Tasks provide a persistent, hierarchical dependency graph stored as real files, enabling reliable long‑term project orchestration.

Multi‑session sharing mechanism

Export the same CLAUDE_CODE_TASK_LIST_ID before launching Claude Code. All sessions (interactive, CLI, or Agent SDK) read and write the same JSON files, so a status change in one session instantly becomes visible to the others.

CLAUDE_CODE_TASK_LIST_ID=my-project claude -p "Complete the next pending task"

Practical usage guide

Basic workflow

Ask Claude to decompose a project into tasks. Example prompt:

Create tasks for building a user authentication system with JWT tokens

The model returns a set of tasks with appropriate blocks / blockedBy relationships. A typical list might look like:

#1 [pending] Initialize project and install dependencies
#2 [pending] Design JWT schema (blocked by #1)
#3 [pending] Implement token issuance (blocked by #2)
#4 [pending] Add refresh‑token endpoint (blocked by #3)
#5 [pending] Write integration tests (blocked by #4)

Cross‑session sharing

Set the environment variable in each terminal before starting Claude:

export CLAUDE_CODE_TASK_LIST_ID=my-auth-project
claude

Or invoke the CLI directly:

CLAUDE_CODE_TASK_LIST_ID=my-auth-project claude -p "Complete the next pending task"

The same ID can be used in the Agent SDK, allowing automated agents to pull tasks, work on them, and push updates.

Recommended end‑to‑end workflow

Define the overall project requirements.

Prompt Claude to split the work; Claude returns a task list with explicit dependencies.

Launch one or more sub‑agents, each assigned a branch of the dependency graph.

Each sub‑agent operates in its own context but reads/writes the shared task list.

When a task reaches completed, Claude automatically unblocks dependent tasks, which become eligible for execution by any agent.

When to adopt Tasks

Multi‑file feature development (e.g., authentication, payment integration).

Large refactors that touch several modules.

Long‑running projects that span multiple interactive sessions.

Coordination of several sub‑agents handling distinct parts of a codebase.

Tasks that may need to be paused and resumed later.

Quick bug fixes, single‑file edits, or problems Claude can solve in a single turn are better left to the original Todo mechanism.

Version requirement

Tasks are available starting from Claude Code version 2.1.17 . Ensure the runtime is updated before using the API.

Summary

Claude Code Tasks turn AI‑assisted coding from a one‑shot code generator into a project‑level orchestration tool. By persisting tasks as JSON files, exposing explicit dependency edges, and synchronizing state across sessions via CLAUDE_CODE_TASK_LIST_ID, developers can manage complex workflows, coordinate multiple sub‑agents, and treat Claude as a collaborative team member rather than a transient assistant.