vault backup: 2026-04-17 13:18:19

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.

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 |
 

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 |

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*

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
 ---