todo-ledger

How it works

Where items come from, how they close, and where they live.

How items get in

SourceWhen
toolClaude calls park_item while it works.
scanThe end-of-turn scan finds a deferral Claude did not record.
todowriteClaude writes a task list with TodoWrite. Entries are mirrored. If Claude removes an entry, its mirror is dropped. Subagent lists are ignored.
manualYou use /todo add.

The end-of-turn scan

After Claude finishes a reply, a short pass runs when both are true: the reply is 400 characters or longer, and Claude parked nothing that turn. Subagent turns are never scanned.

It asks Claude Haiku, through your own Claude Code session, two things about that reply, with your message and the current open items for context:

  1. Did Claude defer or propose anything it did not record? New items are added with a short description.
  2. Did the conversation settle any open item? An item can be marked approved, rejected, done or duplicate, each with a note saying so.

The scan will not bring back an item you closed in the last 30 days, whether the title matches exactly or closely. Seeing a known item again adds nothing: no new item and no note.

Cost. Each scan is one small Haiku request on your Claude usage. There is no setting to switch it off yet. To stop it, disable the plugin: /plugin disable todo-ledger@todo-ledger.

Duplicates

The same title in the same project is one item. When Claude parks something that may already exist, its instructions tell it to look first and update the existing item instead of adding a second.

Where the files live

One JSON file per item:

SystemFolder
macOS, Linux~/.claude/todo-ledger/items/
Windows%USERPROFILE%\.claude\todo-ledger\items\
{
  "id": "20261012-0951-3c1f",
  "title": "Retry failed webhook deliveries",
  "body": "Failed webhook deliveries are dropped today…",
  "kind": "deferred",        // todo | deferred | proposal | discussion
  "origin": "agent",         // agent | human
  "status": "open",          // open | in_progress | done | dropped
  "project": "billing-api",
  "sessionId": "…",
  "sessionName": "webhook-fix",
  "source": "tool",           // tool | todowrite | scan | manual
  "createdAt": "2026-10-12T09:51:04.000Z",
  "updatedAt": "2026-10-12T09:51:04.000Z",
  "notes": [{ "by": "human", "text": "only retry on 5xx", "at": "…" }]
}

Every session on the machine shares the folder. Open sidebars pick up changes within about ten seconds, or at once with /todos refresh. To back up the list, copy the folder.

What leaves your machine