tracking-todos

Tracking Todos

Maintain a structured, persistent task list while working through multi-step requests. Track progress explicitly, mark completion honestly, and make the plan visible to Oskar.

When to Use

Use proactively when:

• Request requires 3+ distinct steps or actions
• User provides multiple tasks (numbered, comma-separated, or a list)
• Work spans multiple tool calls, file edits, or research phases
• Non-trivial planning would otherwise happen implicitly in your head
• User explicitly asks for a todo list

Skip when:

• Single, straightforward task
• Purely conversational or informational exchange
• Task completes in <3 trivial steps
• Quick fact lookup or recall

When in doubt, use it. Being explicit about multi-step plans makes failure modes visible.

Schema

Each todo has exactly three string fields:

• content — imperative form ("Run tests", "Fix auth bug")
• status — one of: pending, in_progress, completed
• activeForm — present continuous ("Running tests", "Fixing auth bug")

Both content and activeForm are required for every todo. The activeForm is what gets shown while a task is executing.

API

from todos import get_todos, write_todos, abandon, render

# Read current list
todos = get_todos()

# Replace entire list (Claude Code semantics — one call, whole list)
write_todos([
    {"content": "Fetch issue body", "status": "in_progress", "activeForm": "Fetching issue body"},
    {"content": "Draft fix plan", "status": "pending", "activeForm": "Drafting fix plan"},
    {"content": "Implement and test", "status": "pending", "activeForm": "Implementing and testing"},
])

# Display to Oskar
print(render())

# Discard remaining todos when starting fresh unrelated work
abandon()

write_todos() validates schema and that at most one item is in_progress. When every item is completed, it auto-clears the list (matches Claude Code behavior — done-state is empty-state).

Behavioral Rules

One in_progress at a time, strictly. Before starting work on a task, set it to in_progress. Never have two in_progress items simultaneously. The validator enforces this.