What's New?
Beyond Simple To-Do Lists
JSON-Based Tasks
Tasks are stored as structured JSON files rather than plain markdown. Each task includes metadata like status, dependencies, blockers, and ownership. This enables programmatic manipulation and precise tracking across sessions.
Dependency Graphs
Tasks can declare blocks and blockedBy relationships. Claude Code understands which tasks must complete before others can start, preventing work on blocked items and surfacing ready-to-work tasks automatically.
Parallel Sub-Agents
Multiple tasks without dependencies can be processed concurrently using sub-agents. This parallelization significantly reduces total completion time for complex projects with many independent work items.
Task Structure
The JSON Schema
{
"id": "task-001",
"subject": "Implement user authentication",
"description": "Add JWT-based auth with refresh tokens",
"status": "in_progress",
"activeForm": "Implementing authentication",
"owner": "main-agent",
"blocks": ["task-003", "task-004"],
"blockedBy": ["task-002"],
"metadata": {
"priority": "high",
"component": "auth"
}
}
TaskCreate
Task created, waiting to be claimed by an agent
TaskUpdate
Agent claims task and begins work
blockedBy
Waiting on dependency tasks to complete
status: completed
Work finished, unblocks dependent tasks
Context Optimization
Preventing Long Session Degradation
External State Storage
Tasks live in files, not in the conversation context. This means Claude Code can offload state management to the filesystem, preserving context window space for actual code analysis and generation work.
Reduced Context Bloat
Traditional approaches accumulate task lists in conversation history. The JSON-based system keeps only active task references in context, with full details fetched on-demand via TaskGet.
Session Recovery
If a session crashes or is interrupted, task state persists on disk. A new Claude Code session can pick up exactly where the previous one left off by reading the task files.
Multi-Agent Handoff
Sub-agents spawned via the Task tool can claim specific tasks. Each agent works independently, updating shared task state. The parent agent monitors progress without holding full task context.
Progress Visibility
The TaskList tool provides a lightweight summary view. Users see overall progress, blocked items, and what's being worked on without dumping full task details into the conversation.
Focused Execution
Claude Code can focus on one task at a time, fetching only the relevant task details. This task-centric approach prevents the scattered attention that emerges in long, unstructured sessions.
Version Control Integration
Git-Friendly Task Management
File-Based Storage
Tasks are stored as regular files that can be committed to your repository. Track task history alongside code changes. See which tasks were active when specific commits were made.
Branch Synchronization
Different branches can have different task states. Feature branches carry their own task context. Merge task files just like code when branches converge.
Multi-Machine Sync
Push task files to a remote repository and pull them on another machine. Continue a Claude Code session from your laptop that you started on your desktop.
my-project/ ├── .claude/ │ └── tasks/ │ ├── task-001.json # Individual task files │ ├── task-002.json │ └── task-003.json ├── src/ └── .gitignore # Add to .gitignore if you want private tasks # .claude/tasks/ # Or commit them for team visibility git add .claude/tasks/ git commit -m "Add authentication tasks"
Parallel Sub-Agents
Concurrent Task Execution
Independent Execution
Tasks without blockers can be assigned to separate sub-agents. Each agent runs in its own context, working independently. The main agent orchestrates and monitors progress.
Throughput Scaling
A project with 10 independent tasks can potentially complete 10x faster with parallel execution. Dependencies create serialization points, but independent work proceeds concurrently.
Resource Management
Sub-agents consume API tokens independently. Complex projects can be configured to run multiple agents in parallel, with the task system preventing conflicts through ownership tracking.
# Main agent identifies parallelizable tasks TaskList # Shows: task-002 (pending), task-003 (pending), task-004 (blocked) # Spawn sub-agents for independent tasks Task { "subagent_type": "general-purpose", "prompt": "Claim and complete task-002", "run_in_background": true } Task { "subagent_type": "general-purpose", "prompt": "Claim and complete task-003", "run_in_background": true } # Both agents work simultaneously # task-004 unblocks when task-002 completes
vs. Ralph Wiggum Loop
Different Philosophies
| Aspect | Task Management System | Ralph Wiggum Loop |
|---|---|---|
| Approach | Explicit, manageable task lists | Single continuous autonomous prompt |
| State Management | JSON files on disk | PROMPT.md + @fix_plan.md |
| Dependencies | First-class support with blocks/blockedBy | Implicit through task ordering |
| Parallelization | Native sub-agent support | Single sequential loop |
| Session Boundaries | Tasks persist across sessions | Loop continues until complete |
| User Intervention | Granular control per task | Minimal, loop runs autonomously |
| Best For | Complex projects with many dependencies | Well-defined, linear projects |
When to Use Tasks
Choose the task management system when you have complex projects with many interdependent components, need to pause and resume work across sessions, or want granular visibility into progress.
When to Use Ralph
Choose Ralph when you have a well-defined project that can be described in a single prompt, want fully autonomous execution, and prefer minimal intervention during development.
Complementary Tools
These approaches aren't mutually exclusive. Ralph could potentially adopt the task management system internally, gaining dependency tracking while maintaining its autonomous loop philosophy.
Getting Started
Using the Task System
# Create a new task "Create a task to implement the login form with email and password fields" # List all tasks "What tasks do I have?" "Show me the task list" # Get full task details "What are the details of the login form task?" # Update task status "Start working on the login form task" "Mark the authentication task as in progress" # Add dependencies "The API integration task is blocked by the login form task" "Task 3 depends on task 1 and task 2" # Mark complete "Mark the login form task as done" "Complete task 1"
Claude Code handles the underlying tool calls automatically. You interact with the task system using natural language, and Claude translates your requests into the appropriate TaskCreate, TaskList, TaskGet, and TaskUpdate operations.
The task management system is available in Claude Code today. Create explicit task lists, manage dependencies, and leverage parallel sub-agents for faster project completion.
TaskCreate, TaskList, TaskGet, TaskUpdate