This article was written by Claude (AI) with human review and editing. The workflow described is a real technique I use daily with Claude Code.

If you use Claude Code for more than one session on a project, you’ve probably hit this wall: you start a new session, Claude has no idea what you were working on, and you spend the first five minutes re-explaining context. I solved this with one file — TODO.md.
The Problem: Context Doesn’t Survive Between Sessions
Claude Code sessions are stateless by default. Each new terminal window starts from scratch. Even with CLAUDE.md files providing project context and the MCP memory server storing long-term knowledge, there’s a gap: what was I working on right now? Memory stores facts. CLAUDE.md stores conventions. But neither tracks the live state of your work — what’s done, what’s in progress, and what’s next.
I needed something lightweight that could answer one question at the start of every session: “Where did I leave off?”
The Solution: A TODO.md at Every Level
I now maintain TODO.md files at two levels:
- Global (
~/TODO.md) — Cross-project tasks and priorities - Per-project (
project/TODO.md) — Project-specific work items
Each project’s CLAUDE.md references its TODO.md, so Claude reads it automatically at the start of every session. And my global CLAUDE.md instructs Claude to check ~/TODO.md for cross-project work.
Here’s the instruction I add to every project’s CLAUDE.md:
## Task Tracking
- **Always check TODO.md** before starting work
- **Update TODO.md** as tasks are completed (`[x]`), started (`[~]`), or skipped (`[-]`)
- Keep TODO.md as the single source of truth for project statusAnd in my global ~/.claude/CLAUDE.md:
- every project should have a `TODO.md` at the root — read it at the start
of each session via the project's `CLAUDE.md` (which should reference it).
Use it to track pending tasks, priorities, and completed work.
Update it as tasks are added or finished.
- at the start of every session, read the global `~/TODO.md` for cross-project
tasks and priorities. Update it as tasks are added or finished.What a TODO.md Looks Like in Practice
Here’s a real example from one of my projects — a mushroom foraging guide site with 800+ pages:
# Mushroom Explorer TODO
## In Progress
- [~] Generate fal.ai images for 568 new state guides (~$1.70)
- [~] Resubmit 155 rate-limited IndexNow URLs
## Pending
- [ ] Enable Cloudflare R2 public access for CDN images
- [ ] Set up Fly.io R2 secrets for production
- [ ] Generate 50 new spring 2026 blog articles
- [ ] WebP conversion for all images (cwebp not installed)
## Completed
- [x] Scale state guides from 50 to 618 using parallel agents
- [x] Upload 82 images to Cloudflare R2 bucket
- [x] Fix mobile map invisible bug (flex-1 → shrink-0 h-[500px])
- [x] Set up GA4 automated weekly reporting
- [x] Regenerate all Ollama articles with Claude OpusWhen Claude opens a new session and reads this file, it immediately knows: images are being generated, IndexNow needs a retry, and there’s a backlog of blog articles to write. No explanation needed from me.
Why Not Just Use Memory or CLAUDE.md?
I use all three, and they serve different purposes:
- MCP Memory — Long-term knowledge: tech stacks, deployment configs, architectural decisions, billing info. Things that rarely change.
- CLAUDE.md — Project conventions: coding standards, deployment patterns, verification requirements. The “how we do things here” document.
- TODO.md — Live work state: what’s done, what’s next, what’s blocked. Changes every session.
Think of it this way: memory is your team wiki, CLAUDE.md is your team’s engineering handbook, and TODO.md is today’s sprint board. You need all three.
The Global TODO: Cross-Project Coordination
The global ~/TODO.md is where I track work that spans projects or doesn’t belong to any single codebase:
# Global TODO
## Pending
- [ ] Write blog article about TODO.md workflow
- [ ] Set up Resend email for mushroom-explorer newsletter
- [ ] Review GA4 weekly reports across all sites
## Completed
- [x] Set up Cloudflare R2 for mushroom-explorer images
- [x] Add Google Analytics to all 5 content sitesAt the start of every session — regardless of which project I’m working in — Claude reads this file first. If I open a session on my coffee explorer project and the global TODO says “review GA4 reports across all sites,” Claude can proactively surface that.
Tips for Getting the Most Out of TODO.md
After a few months of using this system, here’s what I’ve learned:
1. Use Simple Markers
I use three markers that Claude understands naturally:
[ ]— Pending (not started)[~]— In progress (started but not done)[x]— Completed[-]— Skipped or deprioritized
Keep it simple. Claude parses these perfectly and updates them as work progresses.
2. Include Cost Estimates
For tasks that involve API calls or cloud services, I note the estimated cost right in the task:
- [ ] Generate fal.ai images for 568 state guides (~$1.70)
- [ ] Run content health check across all 800+ pages (~$0.50 API costs)This helps me prioritize and prevents surprise bills. Claude can also reference these estimates when suggesting what to work on next.
3. Let Claude Update It
Don’t manually edit TODO.md — let Claude do it as part of the workflow. When Claude finishes a task, it marks it [x] and often adds new tasks it discovered along the way. This creates an organic, always-current task list without any extra effort from you.
4. Keep Completed Items (Briefly)
I keep completed items in the file for a few sessions before archiving them. This gives Claude context about recent work — it knows that R2 was just set up, so it won’t suggest setting it up again. After a while, move old completed items to an archive section or delete them to keep the file scannable.
The Full System: Memory + CLAUDE.md + TODO.md
Here’s how all three pieces work together in a typical session:
- Session starts — Claude reads
CLAUDE.md(loaded automatically), checks~/TODO.mdandproject/TODO.md, and queries MCP memory for relevant context - Claude picks up where I left off — “I see you were generating state guide images. 568 are done, and R2 CDN setup is next. Want me to continue?”
- Work happens — Claude completes tasks, marks them
[x], discovers new work, adds it as[ ] - Session ends — TODO.md is updated, memory stores any new decisions or patterns, and the next session has full context
It’s a simple system, but it transformed my workflow. No more re-explaining context. No more lost work items. No more “wait, what was I doing?” Every session starts productive from minute one.
The TODO.md pattern costs nothing, takes seconds to set up, and pays for itself in the first session. If you’re using Claude Code for any project that spans multiple sessions, add one today. Your future self will thank you.









