メインコンテンツへスキップ
Todo 追跡は、タスクを管理し、ユーザーに進捗を表示するための構造化された方法を提供します。Claude Agent SDK には、複雑なワークフローを整理し、ユーザーにタスク進捗を知らせるのに役立つ組み込み todo 機能が含まれています。
TypeScript Agent SDK 0.3.142 および Claude Code v2.1.142 以降、セッションは TodoWrite の代わりに構造化された Task ツール TaskCreateTaskUpdateTaskGet、および TaskList を使用します。監視コードの変更方法については、Task ツールへの移行を参照してください。このページの例では、まだ移行していないセッションの TodoWrite を引き続き表示するために CLAUDE_CODE_ENABLE_TASKS=0 を設定しています。

Todo ライフサイクル

Todo は予測可能なライフサイクルに従います:
  1. 作成 - タスクが識別されたときに pending として作成される
  2. アクティベート - 作業が開始されたときに in_progress に変更される
  3. 完了 - タスクが正常に完了したときに完了する
  4. 削除 - グループ内のすべてのタスクが完了したときに削除される

Todo が使用される場合

SDK は以下の場合に自動的に todo を作成します:
  • 複雑なマルチステップタスク - 3 つ以上の異なるアクションが必要な場合
  • ユーザー提供のタスクリスト - 複数のアイテムが言及されている場合
  • 非自明な操作 - 進捗追跡の恩恵を受ける場合
  • 明示的なリクエスト - ユーザーが todo 整理を要求した場合

Todo 変更の監視

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",
  // Re-enable TodoWrite, which this example monitors. Without it, the SDK uses
  // Task tools instead and these tool_use blocks never appear.
  options: { maxTurns: 15, env: { ...process.env, CLAUDE_CODE_ENABLE_TASKS: "0" } }
})) {
  // 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}`);
        });
      }
    }
  }
}

リアルタイム進捗表示

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,
      // Re-enable TodoWrite, which this tracker watches for.
      options: { maxTurns: 20, env: { ...process.env, CLAUDE_CODE_ENABLE_TASKS: "0" } }
    })) {
      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");

Task ツールへの移行

Task ツールは、単一の TodoWrite 呼び出しを、各新規アイテムの TaskCreate と各ステータス変更の TaskUpdate に分割し、TaskListTaskGet はモデルが現在のリストを読み戻すために利用可能です。監視コードは引き続きアシスタントストリーム内の tool_use ブロックを検査しますが、すべての呼び出しでリスト全体を置き換える代わりに、タスク ID でキー付けされたマップを保持します。Task ツールは TypeScript Agent SDK 0.3.142 および Claude Code v2.1.142 以降のデフォルトであるため、options.env の変更は不要です。
TodoWrite を使用Task ツールを使用
1 つのツール呼び出しで完全な todos 配列を書き直すTaskCreate は 1 つのアイテムを追加し、TaskUpdatetaskId で 1 つのアイテムをパッチする
block.name === "TodoWrite" に一致block.name === "TaskCreate" または "TaskUpdate" に一致
アイテム形状:{ content, status, activeForm }TaskCreate 入力:{ subject, description, activeForm?, metadata? }TaskUpdate 入力:{ taskId, status?, subject?, description?, activeForm?, addBlocks?, addBlockedBy?, owner?, metadata? }status"pending""in_progress"、または "completed";削除するには status: "deleted" を設定
block.input.todos を直接レンダリング呼び出し全体でアイテムを蓄積するか、ストリームから TaskList ツール結果のスナップショットを読み取る
割り当てられたタスク ID は TaskCreate 入力にはありません。マッチング tool_result{ task: { id, subject } } として返されるため、マップをキー付けするために結果ブロックからそれをキャプチャします。次の例は、Todo 変更の監視ループへの最小限の変更を示しています。完全なリストをレンダリングするには、ストリーム内の TaskList ツール結果を監視するか、TaskCreate 結果と TaskUpdate 入力をマップに蓄積します:
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Optimize my React app performance",
})) {
  if (message.type !== "assistant") continue;
  for (const block of message.message.content) {
    if (block.type !== "tool_use") continue;
    if (block.name === "TaskCreate") {
      const input = block.input as { subject: string };
      console.log(`+ ${input.subject}`);
    } else if (block.name === "TaskUpdate") {
      const input = block.input as { taskId: string; status?: string };
      if (input.status) console.log(`  ${input.taskId} -> ${input.status}`);
    }
  }
}

関連ドキュメント