deliberate.codes

Practical AI for data & software engineers. What works, no hype.

Claude Code's task management tools

TIL · · 2 min read

Claude Code includes internal task management tools to manage and track multistep work.

TaskCreate#

Creates a task in Claude’s internal task list. Each task tracks progress through pending, in_progress, and completed states.

TaskCreate(
  subject: "Add user authentication",
  description: "Implement JWT-based auth with refresh tokens",
  activeForm: "Adding user authentication"
)

Key fields:

  • subject: imperative form (“Add feature”)
  • description: detailed requirements and acceptance criteria
  • activeForm: present continuous shown in spinner while working (“Adding feature”)

TaskUpdate#

Updates task status or properties. Mark tasks in_progress before starting work, completed when done.

TaskUpdate(taskId: "1", status: "in_progress")

TaskUpdate(taskId: "1", status: "completed")

Dependencies control execution order:

  • addBlockedBy: tasks that must complete first
  • addBlocks: tasks waiting on this one
TaskUpdate(taskId: "2", addBlockedBy: ["1"])

TaskList and TaskGet#

TaskList returns all tasks with summary info: id, subject, status, owner, and blockedBy. Use it to see available work and overall progress.

TaskGet fetches full details for a specific task including the complete description and dependency graph.

Task (sub-agents)#

The Task tool spawns specialized sub-agents that work autonomously and return results. Each agent type has specific capabilities and tool access.

Task(
  subagent_type: "Explore",
  description: "Find auth implementation",
  prompt: "Locate all authentication-related code"
)

Available agent types:

  • Explore: fast codebase search and exploration
  • Plan: implementation strategy design
  • Bash: command execution
  • general-purpose: multi-step research tasks

Sub-agents run in their own context window, isolated from the parent conversation. They return a single result when complete. This isolation means they don’t consume the parent’s context budget, but they also can’t see ongoing conversation state unless you include it in the prompt.

You can run multiple agents in parallel by issuing multiple Task calls in one message. Use run_in_background: true to continue working while an agent runs.

How to invoke#

Claude Code uses these tools automatically when appropriate. To encourage their use, prompt for multi-step workflows explicitly:

  • “Break this down into tasks and track progress”
  • “Create a task list for implementing this feature”
  • “Use sub-agents to explore the codebase in parallel”

Conclusion#

Task tools bring structure to complex work. They make progress visible, enable parallel execution via sub-agents, and help Claude maintain focus across multi-step implementations.