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

Daftar Todo

Lacak dan tampilkan todos menggunakan Claude Agent SDK untuk manajemen tugas yang terorganisir

Pelacakan todo menyediakan cara terstruktur untuk mengelola tugas dan menampilkan kemajuan kepada pengguna. Claude Agent SDK mencakup fungsionalitas todo bawaan yang membantu mengorganisir alur kerja yang kompleks dan membuat pengguna tetap terinformasi tentang perkembangan tugas.

Siklus Hidup Todo

Todos mengikuti siklus hidup yang dapat diprediksi:

  1. Dibuat sebagai pending ketika tugas diidentifikasi
  2. Diaktifkan menjadi in_progress ketika pekerjaan dimulai
  3. Diselesaikan ketika tugas selesai dengan sukses
  4. Dihapus ketika semua tugas dalam grup selesai

Kapan Todos Digunakan

SDK secara otomatis membuat todos untuk:

  • Tugas multi-langkah yang kompleks memerlukan 3 atau lebih tindakan yang berbeda
  • Daftar tugas yang disediakan pengguna ketika beberapa item disebutkan
  • Operasi non-trivial yang mendapat manfaat dari pelacakan kemajuan
  • Permintaan eksplisit ketika pengguna meminta organisasi todo

Contoh

Memantau Perubahan 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}`);
});
}
}
}
}

Tampilan Kemajuan Real-time

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");

Migrasi ke alat Task

Alat Task membagi panggilan TodoWrite tunggal menjadi TaskCreate untuk setiap item baru dan TaskUpdate untuk setiap perubahan status, dengan TaskList dan TaskGet tersedia untuk model membaca kembali daftar saat ini. Kode pemantauan Anda masih memeriksa blok tool_use dalam aliran asisten, tetapi mempertahankan peta yang dikunci berdasarkan ID tugas alih-alih mengganti seluruh daftar pada setiap panggilan. {/* min-version: 2.1.142 */}Alat Task adalah default mulai dari TypeScript Agent SDK 0.3.142 dan Claude Code v2.1.142, jadi tidak ada perubahan options.env yang diperlukan.

Dengan TodoWrite Dengan alat Task
Satu panggilan alat menulis ulang array todos lengkap TaskCreate menambahkan satu item, TaskUpdate menambal satu item berdasarkan taskId
Cocokkan block.name === "TodoWrite" Cocokkan block.name === "TaskCreate" atau "TaskUpdate"
Bentuk item: { content, status, activeForm } Input TaskCreate: { subject, description, activeForm?, metadata? }. Input TaskUpdate: { taskId, status?, subject?, description?, activeForm?, addBlocks?, addBlockedBy?, owner?, metadata? }. status adalah "pending", "in_progress", atau "completed"; atur status: "deleted" untuk menghapus
Render block.input.todos secara langsung Akumulasi item di seluruh panggilan, atau baca snapshot dari hasil alat TaskList

ID tugas yang ditugaskan tidak ada dalam input TaskCreate. Ini kembali dalam tool_result yang cocok sebagai { task: { id, subject } }, jadi tangkap dari blok hasil untuk mengunci peta Anda. Contoh berikut menunjukkan perubahan minimal ke loop Memantau Perubahan Todo. Untuk merender daftar lengkap, pantau hasil alat TaskList dalam aliran atau akumulasi hasil TaskCreate dan input TaskUpdate ke dalam peta.

Input tool_use yang dialirkan adalah bentuk mentah yang dipancarkan model. Claude Code memperbaiki beberapa nama kunci yang hampir-tetapi-tidak-benar sebelum eksekusi, memetakan id atau task_id ke taskId dan active_form ke activeForm, tetapi perbaikan itu tidak tercermin dalam aliran. Baca bidang input TaskUpdate secara defensif, seperti yang dilakukan sampel di bawah ini, daripada mengasumsikan nama kanonik selalu ada.

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}`);
}
}
}