SpyBara
Go Premium

agent-sdk/todo-tracking.md 2026-06-16 21:57 UTC to 2026-06-17 17:02 UTC

18 added, 4 removed.

2026
Tue 30 23:02 Mon 29 23:02 Sat 27 01:01 Fri 26 23:00 Thu 25 23:58 Wed 24 22:02 Tue 23 22:00 Mon 22 23:59 Fri 19 22:58 Thu 18 22:00 Wed 17 17:02 Tue 16 21:57 Mon 15 23:02 Sat 13 21:59 Fri 12 22:00 Thu 11 23:01 Wed 10 23:57 Tue 9 06:34 Mon 8 06:52 Sat 6 06:24 Fri 5 06:45 Thu 4 06:52 Wed 3 06:53 Tue 2 06:51

Todo リスト

Claude Agent SDK を使用して todo を追跡・表示し、タスク管理を整理します

Todo 追跡は、タスクを管理し、ユーザーに進捗を表示するための構造化された方法を提供します。Claude Agent SDK には、複雑なワークフローを整理し、ユーザーにタスク進捗を知らせるのに役立つ組み込み todo 機能が含まれています。

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 でキー付けされたマップを保持します。{/* min-version: 2.1.142 */}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 入力をマップに蓄積します。

ストリーミングされた tool_use 入力は、モデルが発行した生の形状です。Claude Code は実行前にいくつかの近いが正確でないキー名を修復し、id または task_idtaskId にマッピングし、active_formactiveForm にマッピングしますが、その修復はストリームに反映されません。以下のサンプルのように、常に正規名が存在すると仮定するのではなく、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;
id?: string;
task_id?: string;
status?: string;
};
const taskId = input.taskId ?? input.id ?? input.task_id;
if (taskId && input.status) console.log(`  ${taskId} -> ${input.status}`);
}
}
}