An agent without a plan drifts

What You’ll Learn

  • Why agents need a visible plan for multi-step tasks
  • How to implement a TodoWrite tool that persists a task list
  • How nag reminders keep the agent focused

The Problem

An agent working through a complex task can drift. Without a visible record of what remains, it may skip steps, repeat work, or lose track of dependencies. Halfway through a refactor that touches 10 files, the agent forgets step 3.

The Solution

Give the agent a TodoWrite tool — a durable to-do list it can read and write. The tool becomes the agent’s external working memory for the current session plan.

How It Works

  1. The TodoWrite tool accepts a list of todo items with status fields.
{"name": "todo_write",
 "input_schema": {
     "type": "object",
     "properties": {
         "todos": {
             "type": "array",
             "items": {
                 "type": "object",
                 "properties": {
                     "content": {"type": "string"},
                     "status": {"type": "string",
                                "enum": ["pending", "in_progress",
                                         "completed", "cancelled"]}
                 },
                 "required": ["content", "status"]
             }
         }
     },
     "required": ["todos"]
 }}

  1. The handler updates in-memory state. Nothing complex — just self.todos = input.

  2. A nagging mechanism reminds the agent every N turns if todos are still pending.

if turn_count % 5 == 0 and any(
    t["status"] in ("pending", "in_progress") for t in todos
):
    remaining = [t for t in todos if t["status"] != "completed"]
    messages.append({
        "role": "user",
        "content": f"[REMINDER] Open tasks: {len(remaining)}"
    })

What Changed From s02

ComponentBefore (s02)After (s03)
Tools45 (+ todo_write)
PlanningNoneVisible, persistent list
Nag systemNonePeriodic reminders

Try It

cd learn-claude-code
python agents/s03_todowrite.py
  1. Build a simple Flask web app with 3 routes and tests
  2. Refactor the codebase to use dependency injection
  3. Write a function that takes a list and returns deduplicated, sorted

Key Takeaway

A visible plan is not decoration — it keeps the agent on track when tasks get complex.

Previous Next