Claude Code Tasks vs To-dos: What Each Is For and Where They Live

In Claude Code, a to-do and a task are the same thing under two names. TodoWrite was the original tool Claude used to keep a checklist while it worked. It has since been replaced by default with four task tools — TaskCreate, TaskGet, TaskList and TaskUpdate — which do the same job with more structure: statuses, details and dependencies. Either way, the list is Claude’s own working checklist for multi-step work. It lives on your machine, and nobody else sees it. Work that has to outlive the session or be seen by other people belongs somewhere else.

The to-do list: TodoWrite

Claude Code’s tools reference↗ (opens in a new tab) describes TodoWrite as the tool that “manages the session task checklist”. You have probably seen it without knowing the name: Claude breaks a request into steps, shows them as a list, and ticks them off as it goes. It is disabled by default now, in favour of the four Task tools, and comes back if you start Claude Code with CLAUDE_CODE_ENABLE_TASKS=0.

Tasks: TaskCreate, TaskList, TaskUpdate

The four task tools replace it. Claude creates an item as pending when it identifies a piece of work, sets it in progress when it starts, marks it completed when it finishes, and deletes items it no longer needs. TaskUpdate can also record dependencies between items. According to the Agent SDK documentation↗ (opens in a new tab), Claude reaches for this list on multi-step work — three or more distinct actions, a list of things you asked for, or a long operation — and may skip it for short requests.

In the terminal, Ctrl+T shows or hides Claude’s task list, displaying up to five items at a time. To see everything or clear it, you ask Claude: “show me all tasks”, “clear all tasks”.

One thing that surprises people: on some newer models Claude Code leaves these tools out by default. The documentation’s reasoning↗ (opens in a new tab) is that those models keep track of multi-step work without a written checklist, and the tool definitions take up context. If your list stays empty, that is why. You can opt in with CLAUDE_CODE_ENABLE_TODO_TOOLS=1, or by naming one of the tools in --allowedTools.

Three things called “task”

Much of the confusion comes from one word doing three jobs in Claude Code:

• Claude’s task list — its checklist, filled by TaskCreate and TaskUpdate, toggled with Ctrl+T.
• Background tasks — shells and subagents running while you keep working. /tasks lists these, and TaskStop stops one. The documentation is explicit that this view is separate from Claude’s task list.
• The old Task tool — the tool that launched subagents. It was renamed Agent in version 2.1.63↗ (opens in a new tab); old Task(...) references in settings still work as aliases. That one is about delegating work, not listing it, and has its own article.

What survives the session, and what does not

Claude’s task list is sturdier than the old checklist, but it is still local. What the Claude Code documentation↗ (opens in a new tab) says today:

• Items persist across context compaction, so a long session does not lose its place when older messages are summarised.
• A session you come back to with --resume or --continue still has its items.
• To share one list across sessions, start Claude Code with CLAUDE_CODE_TASK_LIST_ID set; the list is then kept in a named directory under ~/.claude/tasks/.
• Either way, the list is files under ~/.claude/tasks/ on the machine that ran the session.

CLAUDE_CODE_TASK_LIST_ID=billing-refactor claude

That covers a lot: one developer, one machine, a piece of work spread over several sessions. What it does not cover is anyone else. A colleague cannot open your ~/.claude/tasks/ directory. A different assistant — Cursor, Codex CLI, ChatGPT — does not read it. There is no record of who changed an item, no kind, no priority, and no way to say “this one is ready, that one is not”. None of that is a flaw; the list was built as Claude’s scratchpad, and it is a good one.

Where a shared board fits

The clean split is by audience. If only Claude needs it to finish the job in front of it, it is a to-do. If a person needs to see it, decide on it, or pick it up tomorrow, it is a task on a board.

• “Read the failing test, find the cause, write the fix, rerun the suite” — four to-dos. Claude’s business.
• “The invoice page throws a 500 on an empty draft” — a bug on the board. Someone reported it, someone will ask whether it is fixed.
• “While fixing that I noticed the export ignores the currency” — also the board. It is not part of this job, and if it only lives in the session it is gone when the session ends.
• “Refactor billing across the next three sessions” — a card on the board for the outcome, and CLAUDE_CODE_TASK_LIST_ID for Claude’s own steps, if you want them to carry over.

A useful test when you are not sure: imagine the session crashes right now. Anything you would want back tomorrow, from a different machine or in a colleague’s hands, should already be on the board. Anything you would happily let Claude work out again from scratch can stay in its list. Most steps pass that test easily; most findings do not.

The two layers fit together without overlap. The board card says what and why, and ends with what changed and how it was checked. Claude’s task list holds the steps in between. You review the first; you rarely need to read the second.

Telling Claude Code which is which

Claude will not make that split by itself, because from inside a session both look like lists. One short section in CLAUDE.md does it. This assumes a fenbs board is connected over MCP; the tool names are fenbs’s own.

## Tasks, to-dos and the board
- Your task list is for your own steps. Use it as you like.
- Anything a person should see goes on the fenbs board:
  - the job you are working on (move it to "doing", then "done" with a comment)
  - anything you notice but are not asked to fix (fenbs_create_item, lane "backlog")
  - anything you could not finish (comment on the card with why)
- Do not copy your step list onto the board. One comment with the outcome is enough.

The last line matters. An assistant that mirrors every step as a board comment turns a readable history into a second transcript. The board is for outcomes: started, finished, stuck, found something.

What the board adds that a local list cannot

• People. Colleagues and clients see the same board, each with a role, and plan what goes next.
• Any assistant. Claude Code, Cursor or ChatGPT connected over MCP read and write the same cards, and your AI context goes with them.
• A record. Every change is kept with who made it, and an assistant’s changes are named as the assistant’s, not yours. That is the subject of an audit trail for AI agents.
• Kinds and priority. A bug, a feature and an enhancement read differently, and a priority from 1 to 10 says what comes first.