The Four Things Claude Code Tasks Cannot Store — and Why Teams Hit That Wall

On January 22, 2026, Anthropic shipped native task persistence for Claude Code. [1] In the months that followed, developers were still publishing workarounds for what looked like the same problem. [5] [6]

They were not solving the same problem. That distinction is what this post is about.

Claude Code Tasks does exactly what it claims: it stores orchestration metadata — task status, dependencies, ownership — in a local directory that survives session termination and terminal crashes. That is a real capability, and it matters. But the workaround authors — writing in January 2026, March 2026, running their own experiments — were hitting something else. Cross-machine state. Team visibility. Credentials. Evidence of what the agent produced. Those are not bugs in Tasks. They are its designed scope.

Knowing where the scope ends is how you decide whether native Tasks is sufficient for your situation — and if it isn't, what to add. Neither question has a complicated answer once you have the right model.

---

What Claude Code Tasks Actually Is

The data model is worth understanding precisely, because most misalignment between what people expect from Tasks and what they get comes from a fuzzy model of what it stores.

Tasks live in ~/.claude/tasks/ — a local directory on your development machine. Each task is a JSON record carrying the fields an agent needs to orchestrate work: status, dependencies, a name, and ownership information. The dependency model uses blockedBy relationships, and the unblocking is automatic: when a prerequisite task completes, dependent tasks become available without any manual state update. [4]

Session survival is the core guarantee. Tasks persist across terminal crashes and session termination. That is the specific problem Tasks was designed to solve: you spin up a session, the agent claims some work, the terminal dies, you restart — and the work state is still there. Before Tasks, agents started each session from a blank slate. [1]

There are two other design points worth noting. Multiple sessions can share the same task list by pointing at the same directory via environment variable configuration — so a coordinator session and an executor session on the same machine can work against the same backlog without duplicating state. And the documentation acknowledges a practical constraint it calls the "3-Task Rule": keep three active tasks maximum at a time. That limit exists because agent context is finite, and trying to juggle more concurrent work degrades the agent's ability to track any of it. [4]

What Tasks stores, concretely: task status, dependency chains, session-survival of orchestration metadata on a single local filesystem.

What it is not: a cloud database, a team collaboration tool, a secret manager, or an artifact store. Those things are not on the list because they were not the design goal. Understanding that distinction is the whole game.

---

The Four Walls

Every capability has a boundary. For Tasks, there are four places where teams consistently run into the edge of its designed scope. None of them are flaws. They are the natural consequence of building something that does one job well on a single machine.

Wall 1 — No cloud sync

~/.claude/tasks/ is a local directory. That sentence carries the full weight of the limitation.

The moment you move to a second machine — your home laptop, a cloud runner, a spare workstation — the task state is not there. There is no sync mechanism. The agent on the second machine starts from zero on orchestration state even if it has access to the same codebase. [4]

The practical scenario: an engineer pulls work onto their personal laptop to review something after hours. The agent on that machine has no record of what the office machine was working on. Any continuity has to be reconstructed from CLAUDE.md or the git log — which is exactly what the workaround cluster is built around.

Wall 2 — No team access

Tasks has no authentication layer and no concept of roles. There is no shared view. A second developer who joins the project has no way to see what the agent is working on, no history of completed work, and no board state a non-technical stakeholder can read.

The practical scenario: a team lead wants to know what the agent completed this sprint. There is no board to show them. The answer is either a git log, a verbal summary, or a manual export of local JSON files that were designed for the agent, not for human review.

Wall 3 — No credential storage

Tasks stores orchestration metadata. It does not store secrets. API keys, environment variables, and service credentials exist outside the task record.

The practical scenario: the agent needs to call an external service during a work unit. Those credentials have to arrive via environment variables or a separate secret-management mechanism. There is no first-class place in the task record to store "here is what this agent needs access to in order to execute." That overhead gets handled ad hoc, which means it gets handled inconsistently.

Wall 4 — No artifact storage

When an agent finishes a task, the outputs — generated files, test results, screenshots, migration diffs, structured review notes — live on the local filesystem. They are not attached to the task record. They are not addressable by task or work unit.

The practical scenario: an agent completes a feature and generates a Playwright trace and a coverage report. That evidence lives in a folder on the local machine where the run happened. A second agent picking up a related task later has no structured handoff. The first agent's evidence is either reconstructed from git, manually described in a comment, or quietly lost.

---

Why the Workaround Posts Keep Coming

Multiple independent authors published detailed fix protocols for Claude Code state loss through spring 2026. [5] [6] The timing looks like a criticism of Tasks. It isn't.

Read the workaround guides and the gap becomes clear. The dev.to post from January 17 describes the problem: "LLMs can only hold a limited amount of information in their context window, and they tend to forget what they were doing in longer tasks." [5] The March 4 post is more direct: "Claude Code starts every session from zero — no memory of past decisions, debugging breakthroughs, or project context." [6] The fixes they test — CLAUDE.md, auto-memory, recap tools, external memory libraries — all operate at the context layer. They are trying to preserve what the agent _understands_, not just what its task queue contains.

That is a different problem from orchestration persistence. Tasks solved "the agent's work queue survives a session restart." The workaround cluster is solving "the agent's reasoning context survives a session restart." Both problems are real. They are not the same problem.

The two categories are useful to keep separate:

The workaround authors were not writing about outgrowing Tasks. They were solving the context problem, which Tasks was never designed to address. If those two problems look similar from the outside, it is because both feel like "the agent forgot things." The fix layers are different.

---

Tasks Is Enough When... / You've Outgrown It When...

There is a clean decision line. Here it is.

Native Tasks is sufficient when all of these are true:

• Single developer
• Single machine (no handoff to a second laptop, a cloud runner, or CI)
• No shared backlog across simultaneous agents
• No secrets the agent needs to read from the task context
• No non-technical stakeholder needs to see task state
• Projects are short enough that task history doesn't need to persist beyond local disk

If every item on that list applies, Tasks is a solid fit. It does the job it was designed to do, and adding infrastructure on top is unnecessary overhead.

You have likely outgrown native Tasks when any of these are true:

• Two or more developers working the same backlog
• The agent runs on more than one machine — local plus CI, two laptops, a background runner
• Two or more concurrent agents need exclusive claims on the same work items
• The agent needs to read environment credentials from the task context
• A non-technical stakeholder needs a board view of what the agent is working on
• You need to attach evidence — screenshots, test results, generated artifacts — to a task for handoff or review

That second list describes normal team scale. It also describes where teams consistently report hitting trouble: the engineer who went home, the onboarding teammate, the parallel agents producing duplicate branches, the stakeholder asking for a status update. The wall is not a bug. It is the designed boundary of a single-machine tool encountering multi-machine reality.

---

Runtime vs System of Record — The Category Difference

Claude Code is the agent runtime. It executes work. It runs the shell commands, edits the files, calls the services. Tasks is part of that runtime: a local orchestration layer that tells the agent what it is working on, what is blocked, and what is done in this session.

A cloud project board is not a competing runtime. It is a shared system of record — what the team is working on across all sessions, all machines, all time. The board does not run the agent. The agent reads the board, picks up context and acceptance criteria, does the work, and writes results back when it finishes.

The MCP connection is the bridge between them. An agent connects to a shared board over MCP, reads task context, acquires a workflow lock before starting work, writes artifacts when it finishes, and releases the lock. The local task DAG and the shared board operate at different layers, and neither one replaces the other.

Teams that conflate these two layers usually land in one of two places: they over-rely on local Tasks and then hit the four walls, or they dismiss Tasks as unnecessary and lose the cheap, low-overhead session continuity it provides. Both are mistakes. Each layer has a job. Neither job is glamorous. Both matter.

The multi-machine version of this in practice — workflow locks, shared backlogs, agent fleets — is covered in detail in Scaling AI Agents Across Machines with the Agiflow CLI.

---

What a Cloud Board Adds — Verified Capabilities

This section is only useful if the capabilities are real, so I will be direct about what is verified and what the honest boundary is.

The capabilities below are confirmed first-hand from Agiflow's live task schema and project-management domain. [7] [8] Agiflow does not run or host AI agents — Claude Code stays the agent runtime. Free plan = 3 projects, no trial.

The tasks themselves carry first-class acceptanceCriteria and testCases fields — [7] which is relevant if you are already using Tasks for its intended purpose and want to connect completion criteria to something a stakeholder can see. The two layers do not fight each other. They each do their job.

For the secrets wall specifically, see AI Agent Secrets Management. For the work hierarchy above a flat task list, see Coordinating Multi-Task AI Workflows with Work Units.

Connect Agiflow to Claude Code via MCP — free for up to 3 projects. The MCP connection lets the agent read task context, acquire locks, write artifacts, and update status from any machine. The board lives in the cloud. The agent stays wherever you run it.

---

TL;DR

The honest answer for most teams running serious agent workloads: use both. Tasks handles the local session orchestration. The cloud board handles everything that needs to outlast the session.

Connect Agiflow to Claude Code via MCP — free for up to 3 projects.

---

References

[1] Anthropic Claude Code Release Notes — https://docs.anthropic.com/en/release-notes/claude-code — Primary Anthropic source for Claude Code capabilities including task persistence and background sessions.

[4] dplooy, Claude Code Tasks: Complete Guide to AI Agent Workflow — https://www.dplooy.com/blog/claude-code-tasks-complete-guide-to-ai-agent-workflow — Documents the Claude Code 2.1 release (January 22, 2026), ~/.claude/tasks/ storage, blockedBy dependency model, and the 3-Task Rule. Captured 2026-06-08.

[5] kiwibreaksme (dev.to), Claude Code Keeps Forgetting Your Project — Here's the Fix (2026) — https://dev.to/kiwibreaksme/claude-code-keeps-forgetting-your-project-heres-the-fix-2026-3flm — Published January 17,

1. Independent workaround guide addressing context persistence after Tasks shipped. Captured 2026-06-08.

[6] hw20200214 (dev.to), Claude Code Forgets Everything Between Sessions — I Tested 5 Fix — https://dev.to/hw20200214/claude-code-forgets-everything-between-sessions-i-tested-5-fixes-199p — Published March 4,

1. Tests CLAUDE.md, auto-memory, claude-mem, Claude-Recap, and Beads as fixes for cross-session context loss.

Confirms the gap is at the context layer, not the orchestration layer. Captured 2026-06-08.

[7] Agiflow create_task MCP tool schema — internal product-knowledge MCP — Verifies first-class acceptanceCriteria (array of {checked, text}), testCases ({text, checked, testType}), status, assignee, priority, and tags on tasks.

[8] Agiflow project-management + mcp-integration domains — internal product-knowledge MCP — Verifies cloud/team access (Durable Objects / R2, multi-tenant orgs), per-environment AES-encrypted vault (VaultEntry), relational artifact tables + R2 storage with attach_task_artifact, and Workflow aggregate distributed locks scoped to (projectId, workUnitId, taskId) with 7 MCP workflow-lock tools.