Tracking Multi-Step Work in Claude Code Now That the Todo Tools Are Off by Default

Why I left the variable alone and built a ledger instead

Once the cause was clear, adding CLAUDE_CODE_ENABLE_TODO_TOOLS=1 would have been the obvious move. For work where a person is watching and steering mid-run, it is worth it.

But the maintenance I hand off runs unattended. What I go back to afterwards is never "what did it say it would do" — it is "which files actually changed." A checklist is a statement of intent made before the work. It is not evidence that the work happened.

In why task granularity decides the quality of a Claude Code TodoList I argued for slicing items into verifiable units. This takes that a step further: stop externalizing the intent at all, and record only what actually occurred.

What I put in place is a work ledger written by a PostToolUse hook. Every file-changing tool call appends one line.

#!/usr/bin/env bash
# ~/.claude/hooks/record-change.sh
# PostToolUse hook, registered with matcher: Edit|Write|NotebookEdit
set -euo pipefail
 
LEDGER_DIR="${CLAUDE_LEDGER_DIR:-$HOME/.claude/ledger}"
mkdir -p "$LEDGER_DIR"
 
# One jq process, not four. Calls with neither file_path nor
# notebook_path are dropped by select. Always exit 0 so a hook
# failure can never take the session down with it.
jq -c --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" '
  (.tool_input.file_path // .tool_input.notebook_path // "") as $f
  | select($f != "")
  | {ts: $ts,
     session: (.session_id // "unknown"),
     agent:   (.agent_id   // "main"),
     tool:    (.tool_name  // "unknown"),
     file:    $f}
' >> "$LEDGER_DIR/$(date -u +%Y-%m-%d).jsonl" 2>/dev/null || true
 
exit 0

The settings side:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write|NotebookEdit",
        "hooks": [
          { "type": "command", "command": "~/.claude/hooks/record-change.sh" }
        ]
      }
    ]
  }
}

agent_id is in there because once subagents run in parallel, "who touched this" is the field you end up wanting. It is populated only when the hook fires inside a subagent.

My first version pulled session_id, agent_id, tool_name, and file_path out with four separate jq calls. Two hundred consecutive runs on my machine (jq 1.6) averaged 95 ms each. Folding them into the single call above brought that to 28 ms, roughly a 3.4x reduction. The per-call difference looks trivial until you remember the hook fires on every file change; across a few hundred edits it is the difference you feel.

The 2>/dev/null || true is deliberate. When malformed JSON arrives, jq writes a parse error to stderr. The hook still exits 0 and the session keeps going, but the error text lands in your terminal and buries the output you were reading.

At eight writers in parallel, the ledger corrupted silently

Here is the part that ran against my expectations.

An append-only log felt safe to write from many processes at once. With short lines it is. Eight processes writing 60 lines each — 480 lines at an average of 163 bytes — came out as 480 valid JSON records.

Long lines are a different story. I repeated the run with paths deep enough to push each record to 5,293 bytes: eight writers, 320 lines total. The file had exactly 320 lines. Piping it through jq, only 232 of them parsed. Eighty-eight records, 27.5% of the run, had been interleaved into garbage.

The line count looking correct is what makes this dangerous. You discover the damage at the moment you need the record.

The boundary sits at the size of a single append. Past roughly 4 KiB, another process's write starts landing in the middle of yours. Parallelism itself is not the problem; line length is. And with forked subagents now running in the background by default, multiple writers on one ledger is an ordinary configuration rather than an exotic one.

The fix is to wrap the append in a lock.

#!/usr/bin/env bash
# Version that survives lines past PIPE_BUF
set -euo pipefail
 
LEDGER_DIR="${CLAUDE_LEDGER_DIR:-$HOME/.claude/ledger}"
mkdir -p "$LEDGER_DIR"
OUT="$LEDGER_DIR/$(date -u +%Y-%m-%d).jsonl"
 
# 9> opens the lock file; flock holds it across the whole append.
# Wrapping the block in { } matters — locking jq alone leaves the
# redirect outside the protected region.
{
  flock 9
  jq -c --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" '
    (.tool_input.file_path // .tool_input.notebook_path // "") as $f
    | select($f != "")
    | {ts: $ts,
       session: (.session_id // "unknown"),
       agent:   (.agent_id   // "main"),
       tool:    (.tool_name  // "unknown"),
       file:    $f}
  ' >> "$OUT" 2>/dev/null || true
} 9>"$LEDGER_DIR/.lock"
 
exit 0

Under the same conditions — eight writers, 5,293 bytes per line, 320 lines — all 320 parsed. I re-measured the short-line cost as well: 28 ms became 30 ms. Two milliseconds to rule out silent corruption is not a difficult trade.

These numbers come from my Linux environment running jq 1.6. The absolute values will move on your machine; the property that long lines start tearing will not.

The ledger only pays off once you build the reader

Accumulating lines is not the point. I wrote a reader that groups by file and orders by the last time each was touched.

#!/usr/bin/env bash
# ~/.claude/hooks/ledger.sh [YYYY-MM-DD]
set -euo pipefail
 
LEDGER_DIR="${CLAUDE_LEDGER_DIR:-$HOME/.claude/ledger}"
DAY="${1:-$(date -u +%Y-%m-%d)}"
FILE="$LEDGER_DIR/$DAY.jsonl"
 
[ -f "$FILE" ] || { echo "no ledger for $DAY"; exit 0; }
 
jq -rs '
  group_by(.file)
  | map({
      file:   .[0].file,
      edits:  length,
      last:   (map(.ts) | max),
      agents: (map(.agent) | unique | join(","))
    })
  | sort_by(.last)
  | .[]
  | "\(.last)  \(.edits)x  \(.agents)  \(.file)"
' "$FILE"

The output looks like this:

2026-08-16T03:07:47Z  2x  main   /repo/src/api/client.ts
2026-08-16T03:07:47Z  1x  ag-7   /repo/src/api/retry.ts

A file returned to several times is usually a place where something was unclear. A checklist's "done" marker never shows that; an edit count does, without being asked. That column is what I use to decide which parts of a run I review myself.

Deciding on the reader first also settles what belongs in the writer. Do it the other way round and you pack everything into each record, the lines grow, and you drift toward the corruption above.

Restore, or replace

Neither answer is universally right. It comes down to the shape of the work. Mine splits like this.

Worth restoring the variable

• Work where someone is watching and may change direction partway through
• Agent teams that divide labor through the shared task list; members without it fall back to messages, which costs turns
• Work where you need to walk someone else through the procedure

Better served by the ledger

• Unattended scheduled runs, where the result matters and the intent does not
• Long sessions with little context to spare; you reclaim the whole tool-definition-and-reminder budget
• Work you later want to reconcile mechanically against what changed

You can also decide this per session rather than globally. Naming a tool at launch is enough: claude --allowedTools TaskCreate loads it for that run alone.

If you work in a team, decide once and write it down somewhere the whole team reads. A mixed setup, where some members hold the shared task list and others coordinate by message, is the configuration that produces the confusing failures: work looks assigned from one side and invisible from the other, and nobody's logs disagree. Making it uniform in either direction costs less than diagnosing it twice.

For now I leave my interactive sessions as they are and keep the ledger running everywhere. Losing the checklist felt unsettling at first, but the discomfort lasted exactly one day. Once you get used to reading results, it becomes clear how little the intent was doing for you.

Start with just the PostToolUse hook and one ordinary run. Read that day's ledger and see which files you kept coming back to. That is the part worth cleaning up next.