DEV Community

Great Work
Great Work

Posted on Originally published at taskhold.com

How to share Claude Code's task list across sessions (and keep worktrees apart)

#git #productivity #claude #ai

Originally published at taskhold.com.

Short answer: Start each session with the same CLAUDE_CODE_TASK_LIST_ID (for example CLAUDE_CODE_TASK_LIST_ID=my-project claude) and they read and write one list stored in ~/.claude/tasks/my-project. Set it in the shell per worktree, not in .claude/settings.json: since v2.1.63 that file is shared by every worktree of the repo, so all of them would share one list. The list stays on one machine and inside Claude Code; for other agents or other machines you need a hosted list such as Taskhold.

Claude Code's task list is the checklist Claude keeps while it works (Ctrl+T shows up to five items). By default each session has its own. The CLAUDE_CODE_TASK_LIST_ID environment variable lets several sessions coordinate on one list, which is useful when you split a feature across parallel sessions.

If the list is empty in the first place, the task tools are probably off for your model: see Claude Code task list empty. For several tools on one backlog with a live board of their progress, see running multiple coding agents on one task list.

Share one list between sessions

Give every session the same ID when you start it. Claude Code stores the list in a directory of that name under ~/.claude/tasks/, and each session with the ID reads and updates it.

# terminal 1
CLAUDE_CODE_TASK_LIST_ID=billing-rework claude

# terminal 2, same machine
CLAUDE_CODE_TASK_LIST_ID=billing-rework claude
Enter fullscreen mode Exit fullscreen mode

Both sessions now work from ~/.claude/tasks/billing-rework.

  • Only sessions that have the task tools use the list. Claude Code turns them on by default for Opus 4.7, Sonnet 4.6, Haiku 4.5 and earlier models; on other models opt in with CLAUDE_CODE_ENABLE_TODO_TOOLS=1.
  • Ask Claude "show me all tasks" to see more than the five that Ctrl+T displays.

Why settings.json shares the list with every worktree

Since Claude Code v2.1.63, project config (.claude/settings.json, CLAUDE.md, skills) lives at the repository's shared root, so every git worktree of the repo reads the same file. An env entry for CLAUDE_CODE_TASK_LIST_ID there applies to all of them: worktrees you made to keep features apart end up sharing one task list. The issue that reported it (anthropics/claude-code #78874) was closed for inactivity, so it still applies.

# in each worktree's shell, or a per-worktree .envrc with direnv
export CLAUDE_CODE_TASK_LIST_ID="$(basename "$PWD")"
claude
Enter fullscreen mode Exit fullscreen mode

One list per worktree, named after the worktree folder. Remove the env entry from .claude/settings.json first.

What the shared list doesn't do

  • Other machines. The list is files under ~/.claude/tasks/ on one computer.
  • Other agents. Cursor, Codex and other tools can't read it.
  • Your phone. There's no view outside the terminal, and no way to answer a session that's waiting on you from elsewhere.
  • Progress. Items are pending, in progress or done; there's no per-step progress or record of which session changed what.

When a hosted list fits better

Taskhold is a hosted list that Claude Code, Cursor, Codex and other MCP clients share, on any machine. Each task can carry steps and progress, a blocked task shows the agent's question, and the live board shows every session's progress, including from a phone. Projects are matched by repo folder name, so worktrees can keep separate projects or share one. It costs $12 a month after a 7-day trial; if one machine and Claude Code are all you use, the built-in list is enough.

FAQ

Where does Claude Code store a shared task list?

In a directory named after the ID under ~/.claude/tasks/ on that machine, for example ~/.claude/tasks/billing-rework.

Can I put CLAUDE_CODE_TASK_LIST_ID in settings.json?

You can, but since v2.1.63 every worktree of the repo reads the same .claude/settings.json, so all worktrees share that one list. Set it per shell instead when worktrees should stay separate.

Sources

Related

About Taskhold

Taskhold is a hosted task list shared by a person and their AI coding agents over MCP. Agents break tasks into steps and report progress, and the person watches a live board. $12/month or $120/year per person, 7-day trial with a card, no free plan. Made by Great Work LLC.

To try it, add the MCP server https://taskhold.com/api/mcp to your agent. It connects with no sign-up, and the first time the agent uses Taskhold it gives you a link to start the trial.

Top comments (0)