From 2020a361169a6306f2ff97b7dbf5d49d49cdd04f Mon Sep 17 00:00:00 2001 From: Vadym Samoilenko Date: Fri, 17 Apr 2026 13:18:19 +0100 Subject: [PATCH] vault backup: 2026-04-17 13:18:19 --- 99 Daily/2026-04-17.md | 6 + ...by - a terminal for a more modern age 1.md | 0 ...abby - a terminal for a more modern age.md | 0 wiki/_master-index.md | 2 +- wiki/agent-sdk/_index.md | 1 + wiki/agent-sdk/todo-tracking.md | 130 ++++++++++++++++++ wiki/dotfiles/tabby-terminal.md | 2 +- 7 files changed, 139 insertions(+), 2 deletions(-) rename raw/{ => _processed}/Tabby - a terminal for a more modern age 1.md (100%) rename raw/{ => _processed}/Tabby - a terminal for a more modern age.md (100%) create mode 100644 wiki/agent-sdk/todo-tracking.md diff --git a/99 Daily/2026-04-17.md b/99 Daily/2026-04-17.md index a1d3415..05e9fbd 100644 --- a/99 Daily/2026-04-17.md +++ b/99 Daily/2026-04-17.md @@ -284,3 +284,9 @@ tags: [daily] - 13:16 (1min) | `memory-compiler` - **Asked:** Create a structured wiki article on subagents and update the knowledge base indices. - **Done:** Created subagents.md with creation methods, field reference, context isolation, examples, and troubleshooting; updated agent-sdk/_index.md and _master-index.md. +- 13:17 (<1min) | `memory-compiler` + - **Asked:** Compile a raw wiki article about Tabby terminal into the knowledge base. + - **Done:** Merged raw article into existing `wiki/dotfiles/tabby-terminal.md` with enhanced terminal features and SSH capabilities. +- 13:17 (<1min) | `memory-compiler` + - **Asked:** How should a duplicate Tabby terminal article from the raw inbox be handled in the knowledge base? + - **Done:** Added the new raw file to the sources field of the existing tabby-terminal.md article to track provenance without duplicating content. diff --git a/raw/Tabby - a terminal for a more modern age 1.md b/raw/_processed/Tabby - a terminal for a more modern age 1.md similarity index 100% rename from raw/Tabby - a terminal for a more modern age 1.md rename to raw/_processed/Tabby - a terminal for a more modern age 1.md diff --git a/raw/Tabby - a terminal for a more modern age.md b/raw/_processed/Tabby - a terminal for a more modern age.md similarity index 100% rename from raw/Tabby - a terminal for a more modern age.md rename to raw/_processed/Tabby - a terminal for a more modern age.md diff --git a/wiki/_master-index.md b/wiki/_master-index.md index 43f9d2e..fe3a559 100644 --- a/wiki/_master-index.md +++ b/wiki/_master-index.md @@ -30,7 +30,7 @@ This 3-hop pattern works for hundreds of articles without vector search. | [[wiki/web-agency/_index\|web-agency/]] | AI-assisted website building & selling: Claude Code, Nanobanana 2, Kling, LaunchPath MCP | 1 | | [[wiki/dotfiles/_index\|dotfiles/]] | Linux terminal ricing: Kitty, Fish, WezTerm CLI, modern Rust CLI tools, LazyVim, unified themes, Tabby | 19 | -| [[wiki/agent-sdk/_index\|agent-sdk/]] | Claude Agent SDK (formerly Claude Code SDK) — build autonomous AI agents in Python and TypeScript | 25 | +| [[wiki/agent-sdk/_index\|agent-sdk/]] | Claude Agent SDK (formerly Claude Code SDK) — build autonomous AI agents in Python and TypeScript | 26 | | [[wiki/llm-models/_index\|llm-models/]] | OpenAI model catalog — GPT-5.x, o-series reasoning, audio/realtime, embeddings, moderation | 1 | | [[wiki/claude-code/_index\|claude-code/]] | Claude Code product docs — install, capabilities, surfaces, MCP, hooks, scheduling, multi-agent, plugins, skills, channels, error recovery | 11 | diff --git a/wiki/agent-sdk/_index.md b/wiki/agent-sdk/_index.md index ff20938..2097988 100644 --- a/wiki/agent-sdk/_index.md +++ b/wiki/agent-sdk/_index.md @@ -39,3 +39,4 @@ Build production AI agents using the same tools, agent loop, and context managem | [[wiki/agent-sdk/streaming-output\|streaming-output]] | Real-time token/tool streaming: StreamEvent structure, text_delta, input_json_delta, UI patterns, limitations | raw/Stream responses in real-time.md | 2026-04-17 | | [[wiki/agent-sdk/streaming-input\|streaming-input]] | Two input modes: AsyncGenerator (streaming, default) vs string (single message); capabilities, limitations, session resuming | raw/Streaming Input.md | 2026-04-17 | | [[wiki/agent-sdk/subagents\|subagents]] | Spawn subagents programmatically or via filesystem; context isolation, parallelization, tool restrictions, resuming, detection | raw/Subagents in the SDK.md | 2026-04-17 | +| [[wiki/agent-sdk/todo-tracking\|todo-tracking]] | Built-in TodoWrite tool: lifecycle states, automatic triggers, real-time progress display, activeForm field | raw/Todo Lists.md | 2026-04-17 | diff --git a/wiki/agent-sdk/todo-tracking.md b/wiki/agent-sdk/todo-tracking.md new file mode 100644 index 0000000..4c132fe --- /dev/null +++ b/wiki/agent-sdk/todo-tracking.md @@ -0,0 +1,130 @@ +--- +title: "Todo Tracking in the Agent SDK" +aliases: [todo-lists, todo-tracking, sdk-todos] +tags: [agent-sdk, todos, progress-tracking, typescript, workflow] +sources: [raw/Todo Lists.md] +created: 2026-04-17 +updated: 2026-04-17 +--- + +# Todo Tracking in the Agent SDK + +Built-in todo functionality for managing multi-step workflows and displaying task progress to users. Todos are surfaced as `TodoWrite` tool calls in the [[wiki/agent-sdk/agent-loop|agent message stream]]. + +## Todo Lifecycle + +| State | Meaning | +|-------|---------| +| `pending` | Task identified, not yet started | +| `in_progress` | Work actively underway | +| `completed` | Task finished successfully | +| *(removed)* | Cleared when all tasks in a group are done | + +## When the SDK Creates Todos Automatically + +- Complex multi-step tasks requiring **3+ distinct actions** +- User-provided **task lists** (multiple items mentioned) +- Non-trivial operations that benefit from progress visibility +- Explicit user requests for todo organization + +## Monitoring Todo Changes + +Todos appear in the message stream as `tool_use` blocks with `name === "TodoWrite"`: + +```typescript +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 } +})) { + if (message.type === "assistant") { + for (const block of message.message.content) { + if (block.type === "tool_use" && block.name === "TodoWrite") { + const todos = block.input.todos; + todos.forEach((todo, index) => { + const status = + todo.status === "completed" ? "✅" + : todo.status === "in_progress" ? "🔧" + : "❌"; + console.log(`${index + 1}. ${status} ${todo.content}`); + }); + } + } + } +} +``` + +## Real-time Progress Tracker (Class Pattern) + +```typescript +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" ? "🔧" + : "❌"; + // in_progress todos expose an activeForm (present-tense description) + 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(); + } + } + } + } + } +} + +const tracker = new TodoTracker(); +await tracker.trackQuery("Build a complete authentication system with todos"); +``` + +### Notable Todo Fields + +| Field | Notes | +|-------|-------| +| `content` | Task description (pending/completed) | +| `activeForm` | Present-tense description used when `in_progress` | +| `status` | `"pending"` \| `"in_progress"` \| `"completed"` | + +## Key Takeaways + +- Todos surface as **`TodoWrite` tool_use blocks** in the assistant message stream — intercept them the same way as any other tool call. +- The `activeForm` field gives a present-tense verb phrase for the active task, useful for UIs. +- Todos are created **automatically** for 3+ step tasks; no special configuration needed. +- Tracking state is ephemeral per session — persist `this.todos` externally if you need durable progress records. +- Pairs naturally with [[wiki/agent-sdk/streaming-output|streaming output]] for live progress UIs and [[wiki/agent-sdk/sdk-hooks|SDK hooks]] for side-effects on task transitions. + +## Related + +- [[wiki/agent-sdk/agent-loop|Agent Loop]] — how messages and tool calls flow +- [[wiki/agent-sdk/streaming-output|Streaming Output]] — real-time token/tool event handling +- [[wiki/agent-sdk/sdk-hooks|SDK Hooks]] — intercept tool calls pre/post execution +- [[wiki/agent-sdk/user-input-approvals|User Input & Approvals]] — `canUseTool` callback patterns + +--- + +*Source: raw/Todo Lists.md — https://code.claude.com/docs/en/agent-sdk/todo-tracking* diff --git a/wiki/dotfiles/tabby-terminal.md b/wiki/dotfiles/tabby-terminal.md index ff599dc..8160149 100644 --- a/wiki/dotfiles/tabby-terminal.md +++ b/wiki/dotfiles/tabby-terminal.md @@ -2,7 +2,7 @@ title: "Tabby Terminal" aliases: [tabby, eugeny-tabby, terminus-terminal] tags: [terminal, ssh, dotfiles, tools, cross-platform] -sources: [raw/Eugenytabby A terminal for a more modern age.md, "raw/Tabby - a terminal for a more modern age 1.md"] +sources: [raw/Eugenytabby A terminal for a more modern age.md, "raw/Tabby - a terminal for a more modern age 1.md", "raw/Tabby - a terminal for a more modern age.md"] created: 2026-04-17 updated: 2026-04-17 ---