Skip to content

Claude Code Todo Tool

The internal TodoWrite tool — a structured-but-not-structurally-enforced planning scratchpad that claude-code injects into its own context.

Mechanism (per jared-zoneraich)

  • On first user turn, the model emits a to-do block via a tool call. Schema has a version, per-item id (hash), title (human-readable), status, and an optional evidence blob.
  • Rules ("one task at a time", "mark completed", "keep working on in-progress", "break into sub-tasks") are purely prompt-based — not enforced in code.
  • Relies on the fact that 2025-era models are finally good enough at instruction following that prompt-level structure holds. "This would not have worked a year ago."

Why it matters

  1. Forces a plan before tool thrash.
  2. Resumability after crashes / compaction.
  3. UX signal — user sees progress instead of a silent 40-minute loop.
  4. Steerability — user can edit the list.

Zoneraich flags it as a candidate first-class paradigm (alongside claude-code-skills) that other agent builders should copy: model-driven planning via an in-context structured artifact, not an external planner node.