Mastering Persistent Tasks in Claude Code

Overview of Task-Based Orchestration

has evolved beyond simple to-do lists, introducing a robust task system that fundamentally changes how the AI agent manages complex workflows. This shift isn't just cosmetic; it provides a structured framework for the agent to plan, execute, and monitor progress. By breaking down large prompts into discrete, interdependent units, the system allows for better error handling and more transparent execution of multi-step development projects.

Automatic vs. Manual Task Creation

Claude Code intelligently determines when a project requires a formal task list. For simple operations, like generating a single

database table, the agent skips the overhead of task creation to prioritize speed. However, when you present a multi-phase project plan, the orchestrator automatically activates the task_create tool.

If the agent fails to generate a list for a task you deem complex, you can manually intervene using a prompt like this:

I want to see the task list. Use the task create tool to define a plan.

State Persistence and the .cloud Directory

One of the most powerful features of this update is how tasks are stored in your local file system. Every session generates a unique identifier within the .cloud/tasks/ directory. Inside these folders, Claude stores individual JSON files for every subtask. These files track the task's state, blocking dependencies, and specific instructions. This local storage allows the orchestrator to maintain context even if a specific sub-agent fails or the session resets.

Configuring Global Project Persistence

By default, task lists are temporary and tied to a session ID. To make your development workflow resilient against network interruptions or system crashes, you can configure a persistent project ID in your cloud_settings.json file. This ensures that the agent looks for an existing task list upon restart rather than starting from scratch.

{
  "task_list_id": "my-musician-app-project"
}

Syntax Notes and Task Structure

The JSON schema for these tasks includes key fields that manage the logic of the build. Notice how the agent uses blocked_by to ensure sequential execution:

{
  "id": "task_01",
  "description": "Setup authentication resource",
  "status": "completed",
  "blocked_by": [],
  "blocks": ["task_02"]
}

Tips for Large-Scale Refactoring

When working on massive migrations, always define your phases clearly in a markdown document first. When you ask Claude Code to "work on Phase 1," it will parse your document and populate the task list accordingly. This spec-driven development approach keeps the AI on track and prevents it from wandering off-scope during long-running sessions.