Source: https://docs.claude.com/en/docs/agent-sdk/todo-tracking

Agent Skills are now available! Learn more about extending Claude's capabilities with Agent Skills .

Claude Docs home page

English

Search...

Ctrl K

Search...

Navigation

Guides

Todo Lists

Home Developer Guide API Reference Model Context Protocol (MCP) Resources Release Notes

On this page

Todo tracking provides a structured way to manage tasks and display progress to users. The Claude Agent SDK includes built-in todo functionality that helps organize complex workflows and keep users informed about task progression.

Todo Lifecycle

Todos follow a predictable lifecycle:

Created as pending when tasks are identified
Activated to in_progress when work begins
Completed when the task finishes successfully
Removed when all tasks in a group are completed

When Todos Are Used

The SDK automatically creates todos for:

Complex multi-step tasks requiring 3 or more distinct actions
User-provided task lists when multiple items are mentioned
Non-trivial operations that benefit from progress tracking
Explicit requests when users ask for todo organization

Examples

Monitoring Todo Changes

TypeScript

Python

Copy

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Optimize my React app performance and track progress with todos",
  options: { maxTurns: 15 }
})) {
  // Todo updates are reflected in the message stream
  if (message.type === "assistant") {
    for (const block of message.message.content) {
      if (block.type === "tool_use" && block.name === "TodoWrite") {
        const todos = block.input.todos;

        console.log("Todo Status Update:");
        todos.forEach((todo, index) => {
          const status = todo.status === "completed" ? "✅" :
                        todo.status === "in_progress" ? "🔧" : "❌";
          console.log(`${index + 1}. ${status} ${todo.content}`);
        });
      }
    }
  }
}

Real-time Progress Display

TypeScript

Python

Copy

import { query } from "@anthropic-ai/claude-agent-sdk";

class TodoTracker {
  private todos: any[] = [];
  
  displayProgress() {
    if (this.todos.length === 0) return;
    
    const completed = this.todos.filter(t => t.status === "completed").length;
    const inProgress = this.todos.filter(t => t.status === "in_progress").length;
    const total = this.todos.length;
    
    console.log(`\nProgress: ${completed}/${total} completed`);
    console.log(`Currently working on: ${inProgress} task(s)\n`);
    
    this.todos.forEach((todo, index) => {
      const icon = todo.status === "completed" ? "✅" : 
                  todo.status === "in_progress" ? "🔧" : "❌";
      const text = todo.status === "in_progress" ? todo.activeForm : todo.content;
      console.log(`${index + 1}. ${icon} ${text}`);
    });
  }
  
  async trackQuery(prompt: string) {
    for await (const message of query({
      prompt,
      options: { maxTurns: 20 }
    })) {
      if (message.type === "assistant") {
        for (const block of message.message.content) {
          if (block.type === "tool_use" && block.name === "TodoWrite") {
            this.todos = block.input.todos;
            this.displayProgress();
          }
        }
      }
    }
  }
}

// Usage
const tracker = new TodoTracker();
await tracker.trackQuery("Build a complete authentication system with todos");

📄 claude/docs/agent-sdk/todo-tracking

Source: https://docs.claude.com/en/docs/agent-sdk/todo-tracking

Examples

Related Documentation