Background Tasks

Tasks are Claude Code's system for tracking and completing work that outlasts a single context window or session. They evolved from the older TodoWrite tool when it became clear that real projects have dependencies, blockers, and coordination needs that a simple in-memory checklist can't handle. Tasks are stored in ~/.claude/tasks on disk, carry dependency metadata, and broadcast updates to every session currently sharing the same task list, so multiple subagents or windows can collaborate without stepping on each other.

The practical shift: instead of Claude holding its plan in its head (or in an ephemeral todo list), the plan lives in a file the whole team can read and write. That makes work continuable across sessions and inspectable by you at any time.

How you use it day-to-day

• Start a long project. Ask Claude to create a task list before spinning up subagents. It will decompose the work, record dependencies, and use the list to coordinate without losing state if a context window fills up.
• Share a task list across sessions. Set the environment variable before launching: CLAUDE_CODE_TASK_LIST_ID=my-project claude. Every session started this way reads and writes the same list. Works with claude -p and the Agent SDK too.
• Spin up subagents against a shared list. Pass the task list ID to each subagent so they pull from and report back to the same source of truth. When one updates a task, all other sessions are notified immediately.
• Inspect tasks directly. Browse ~/.claude/tasks to see what's queued, in-progress, or blocked. No need to ask Claude; it's just files. Build your own tooling on top if you want.
• Let Claude self-coordinate. For Opus 4.5 and later, Claude can manage the task list autonomously, creating tasks, tracking dependencies, and marking completions without you scripting each step.

Gotchas

• Tasks aren't the same as foreground work. If your project fits in one context window, a task list adds overhead with no benefit. Reach for it when work genuinely spans sessions or subagents.
• The task list ID is the coordination key. If you forget to set CLAUDE_CODE_TASK_LIST_ID, each session gets its own isolated list: updates won't broadcast and collaboration silently breaks.
• Dependency metadata is only as good as the brief. Claude stores dependencies based on what you tell it. Vague briefs produce flat lists with no real blocking logic.
• File-system storage means it persists. Stale task lists from old projects sit in ~/.claude/tasks indefinitely. Prune them manually when a project is done.

When to use Tasks vs foreground work: foreground for anything that fits in one session. Tasks when you're coordinating multiple subagents, resuming across days, or building a pipeline where individual steps need to signal completion to downstream work.