Task Management & Tracking

For complex work involving multiple steps, Claude tracks progress using a task list. This helps you see what’s done, what’s in progress, and what’s left to do.

Task List Overview

When you ask Claude to do something complex, it breaks the work into a visible task list:

> add user authentication with JWT, including tests and documentation

I'll break this down into tasks:

✓ Create User model with password hashing
⚙ Add JWT token generation utilities
○ Create login endpoint
○ Create registration endpoint
○ Add authentication middleware
○ Write unit tests
○ Write integration tests
○ Update API documentation

Let me start with the JWT utilities...

Task States

Symbol	State	Meaning
○	Pending	Not started yet
⚙	In Progress	Currently working on this
✓	Completed	Done

View Current Tasks

Use /todos to see the current task list:

> /todos

Current tasks:
✓ Create User model
✓ Add JWT utilities
⚙ Create login endpoint
○ Create registration endpoint
○ Add tests

Background Tasks

For work that can run independently, Claude can spawn background tasks that operate in parallel with your main session.

View background tasks with /tasks:

> /tasks

Background tasks:
[1] Running tests for auth module - in progress
[2] Generating API documentation - completed

Task List vs Background Tasks

Feature	Task List (`/todos`)	Background Tasks (`/tasks`)
Purpose	Track main session work	Delegate isolated work
Context	Same session	Separate session
Execution	Sequential, one at a time	Parallel, runs independently
Use case	Complex multi-step features	Tests, docs, exploration

Example: Background Task

> run the test suite in the background while I continue working

# Claude spawns a background task:
# - Background: Runs tests in isolation
# - Main session: You continue working
# - Background reports back when done

> /tasks
[1] Running test suite - in progress

# Continue your work...
> implement the login endpoint

# Later:
Background task completed: All 47 tests passed.

When Claude Uses Task Tracking

Claude automatically creates task lists for:

Multi-Step Features

> add a complete user profile feature: avatar upload, bio, social links

✓ Add database migration for profile fields
⚙ Create profile update endpoint
○ Add avatar upload with S3 integration
○ Add input validation
○ Create tests
○ Update frontend models

Sequential Changes

> refactor the authentication system to use dependency injection

✓ Update AuthService to accept dependencies
⚙ Refactor route handlers to use new AuthService
○ Update tests to use DI
○ Update documentation

Requesting Task Breakdown

Explicitly ask Claude to break down work:

> create a task breakdown for adding search functionality
> don't implement yet, just plan the tasks

I'll break this into tasks:

1. Add search index configuration
2. Create search service
3. Add search API endpoint
4. Add pagination for results
5. Add filtering options
6. Write tests
7. Update documentation

Shall I proceed with implementation?

Task Management Patterns

Pattern 1: Review Before Starting

> plan the tasks for migrating from REST to GraphQL
> show me the breakdown before implementing

Here's the task breakdown:

Phase 1: Setup
○ Install GraphQL dependencies
○ Configure GraphQL server
○ Set up schema

Phase 2: Implementation
○ Convert user endpoints
○ Convert product endpoints
○ Convert order endpoints

Phase 3: Testing & Cutover
○ Write tests
○ Update client
○ Deploy

Look good? Shall I start?

Pattern 2: Approve Each Task

> add notifications feature
> wait for my approval after each task

✓ Database migration
Completed! Next task: Create NotificationService

Continue? (yes/no)

Pattern 3: Partial Implementation

> implement tasks 1-3 from the plan
> I'll review before you do tasks 4-6

✓ Task 1: Add database fields
✓ Task 2: Create service class
⚙ Task 3: Add API endpoint
○ Task 4: Tests (paused for review)
○ Task 5: Documentation (paused)

When Tasks Aren’t Needed

Claude doesn’t create task lists for:

Simple single-step work:

> add a comment explaining this function
# Claude just adds the comment

Questions:

> what does this code do?
# No tasks - just analysis

Quick fixes:

> fix the typo in line 42
# Too simple for task tracking

Best Practices

Let Claude Decide — Don’t force task breakdowns for simple work.

Review Complex Breakdowns — For large features, review the task plan before starting:

> show me the task breakdown first
> [review]
> looks good, proceed

Break Mega-Tasks Into Sessions — If you see 20+ tasks, consider splitting across sessions.

Use Background Tasks for Parallel Work — Tests, documentation, and exploration can run in background while you continue.

Task Completion Requirements

Claude should only mark a task as completed when:

✓ The work is actually done
✓ No errors occurred
✓ Tests pass (if applicable)

If Claude marks tasks complete too early:

> wait - that task isn't done, there are still errors
> fix the errors before marking it complete

Troubleshooting

Claude Loses Track of Tasks:

> /compact
# or
> /todos

Too Many Tasks:

> let's focus just on tasks 1-5 for now
> we'll tackle 6-10 in the next session

Summary

Task list (/todos) tracks multi-step work in your current session
Background tasks (/tasks) run isolated work in parallel
One task “in progress” at a time in the main session
Tasks help with progress visibility and interruption recovery
Not needed for simple single-step work
Complex tasks (20+) should be split across sessions