todo.md Works Until the Third Session

You open a fresh Claude Code session on Wednesday, the third one this week on the same project, and the first thing you check out of habit is the todo.md file the agent has been keeping. Two items are checked off that are not actually done. One item you fixed yesterday is back on the list, unchecked, as if Tuesday never happened. This post names the four ways that workflow breaks past a session or two, and the three properties whatever replaces it has to have. It does not argue you should stop using a plain file for everything; for a lot of work, you should keep doing exactly that.

The workflow everyone lands on first, and why it is a good idea

Ask Claude Code to keep a todo.md, check off items as it finishes them, and add new ones it discovers along the way, and it will do it well without any setup. Developers who write this workflow up describe roughly the same shape: task markers like [ ], [~], and [x], a rule that says don't manually edit the file yourself and let the agent own it, and a reference to the file from CLAUDE.md so it loads automatically. It costs nothing, it is plain text you can grep and diff, and it maps directly onto the same checklist shape Claude Code already uses internally for its own TodoWrite tool, which moves each item through pending, in-progress, and completed. None of what follows means this was a bad idea. It is the correct default for a single session, and the honest starting point for understanding where it stops being enough.

Failure 1: the agent rewrites the file instead of appending to it

The first crack shows up as soon as priorities change mid-project. Reordering items, or rewording one to reflect what you actually learned, is a small edit in your head but often becomes a full rewrite of the file on disk, since nothing forces a targeted change to one line. The result is a git diff for a one-word status update that touches the whole file, which makes the file's own history useless as a record of what changed and when. Letting the agent silently regenerate the list, the workaround the workflow itself recommends, papers over this by making rewrites look normal instead of visible.

Failure 2: checkmarks that were never true

A [x] next to an item is a claim, not a fact, and nothing in a plain markdown file checks it. This is a known enough failure that Anthropic wrote a guardrail directly into the tool: Claude Code's own TodoWrite tool description instructs the model to "ONLY mark a task as completed when you have FULLY accomplished it," and lists failing tests, partial implementation, and unresolved errors as explicit reasons not to. Claude Code's own best-practices guide is blunt about why the rule has to exist at all: "Claude stops when the work looks done. Without a check it can run, 'looks done' is the only signal available." A hand-maintained todo.md has none of even that guardrail. Nobody grades the checkbox against a test run, a build, or a second opinion; it is self-reported by the same process that did the work.

Failure 3: no history, so you cannot tell what changed or who changed it

Even when the checkbox is honest today, the file cannot tell you who set it, or whether it was you correcting a mistake or the agent finishing the task on its own. A flat file has one current state and no audit trail unless every checkbox flip gets its own commit, which nobody actually does. That gap is exactly what pushed a chunk of the field toward purpose-built alternatives.

Beads, built by Steve Yegge specifically to fix what he calls the "50 First Dates" problem of an agent waking up with no memory of yesterday, stores issues in a version-controlled database instead of a text file, so every change carries its own history by construction rather than by discipline.

Failure 4: compaction eats the context that made the file legible

The file itself survives on disk no matter what happens inside the conversation, but the reasoning behind a given line often does not. Claude Code's own explanation of how it works describes what compaction actually does: "Claude Code manages context automatically as you approach the limit. It clears older tool outputs first, then summarizes the conversation if needed. Your requests and key code snippets are preserved; detailed instructions from early in the conversation may be lost." A todo item written forty messages before a compaction can end up as a single cryptic line, checked or unchecked, with the discussion that explained why it mattered gone from the context the next reply is generated from. The file did not change. What the file meant did.

Claude Code's todo list is session-scoped by design, not by accident

It is worth being precise about what the built-in tool is actually for, because the failures above are sometimes mistaken for a bug in it. Claude Code's documentation is direct: "Sessions are independent. Each new session starts with a fresh context window, without the conversation history from previous sessions." The todo tool exists to give you a real-time progress display for the plan Claude is executing right now, inside one conversation, the same way a status bar shows a running build. It was never built to be the durable record of a project; that job was deliberately left to files you choose to write, like CLAUDE.md, or to whatever tracker you connect. Expecting the built-in list to survive on its own is expecting a status bar to double as a database, which is the same gap that shows up whenever a fix from one session has to reach the next one without anyone deciding on purpose to write it down.

What a todo file is still the best tool for

None of this is an argument against todo.md, only against expecting it to do a job it was never shaped for. For a single session, a same-day spike, or a task you will finish before you close the terminal, a plain checklist is still the right call: zero setup, no account, and a format the agent already understands natively. It is also a fine scratch space for a solo project scoped to one folder, where you are the only person who ever needs to read it and you are in the terminal often enough to catch a stale checkmark yourself. The failure modes above only start to bite once a project outlives a single sitting, or a second agent or a second person needs to trust what the file says without asking you first.

The three properties any replacement needs

Line the four failures up and the requirements fall out directly:

1. History that survives compaction and rewrites. A change needs a record independent of the conversation that produced it, so a summarized session does not erase the reasoning behind a line.
2. Completion that is checked, not self-reported. Marking something done should depend on more than the same process that did the work saying so.
3. Automatic loading, not remembered retrieval. The next session has to read the current state without anyone, human or agent, having to think to go look for it.

Beads and Task Master, both free, satisfy this from two different angles. Task Master breaks a project into structured task files under a .taskmaster folder, connects over MCP to Claude Code and other agents, and is released under the MIT license with a Commons Clause that blocks reselling the tool itself as a hosted service. Beads takes the database route described above. Trail, distributed as the usetrail MCP connector, takes a third: hosted rather than self-run, with a shared reference memory, gotchas and decisions the agent writes for itself mid-conversation, that the next session and the next person's agent both read automatically on opening the same folder. Worth naming honestly: Beads and Task Master are free because the code and the data live in your repo; Trail costs money past three projects because the memory and the portal live on a server you don't have to run yourself.

Replacing it without leaving the terminal

If you work solo in one repository and finish most tasks inside a session or two, keep the todo.md workflow above and stop here; it is free and it fits the job. If the project runs for weeks and you are comfortable self-hosting a CLI tool, install Beads for the dependency tracking. If you would rather plan from a PRD and already lean on multiple AI providers, Task Master's structure fits better. If more than one person or more than one agent needs to trust the same board without a repo to sync through, that is the case a hosted option earns its keep for. Whichever you pick, the rule does not change: whatever holds your project's state has to outlive the conversation that's currently open, or you are back to reading checkmarks you cannot trust. Read the full comparison of agent-native issue trackers next if you are choosing between more than these three, and see why an oversized CLAUDE.md causes the same kind of silent drift once you're writing rules by hand instead of checkboxes.