Use this tool to create and manage a structured task list for your current coding session. This helps you track progress, organize complex tasks, and demonstrate thoroughness to the user.

## Operations

This tool supports two operations:

### 1. write - Write/Update TODO list
Use this operation to create, update, or replace the entire TODO list.

**Parameters:**
- `operation`: "write" (required)
- `todos`: Complete TODO list with all task items (required). Can be either an array JSON string.

**When to Use:**
- Complex multistep tasks - When a task requires 3 or more distinct steps or actions
- Non-trivial and complex tasks - Tasks that require careful planning or multiple operations
- User explicitly requests todo list - When the user directly asks you to use the todo list
- User provides multiple tasks - When users provide a list of things to be done (numbered or comma-separated)
- After receiving new instructions - Immediately capture user requirements as todos
- After completing a task - Mark it complete and add any new follow-up tasks
- When starting a new task - Mark it as in_progress

### 2. read - Read TODO list
Use this operation to read the current TODO list for the session.

**Parameters:**
- `operation`: "read" (required)

**When to Use:**
- At the beginning of conversations to see what's pending
- Before starting new tasks to prioritize work
- When the user asks about previous tasks or plans
- Whenever you're uncertain about what to do next
- After completing tasks to update your understanding of remaining work
- After every few messages to ensure you're on track

## When NOT to Use This Tool

Skip using this tool when:
1. There is only a single, straightforward task
2. The task is trivial and tracking it provides no organizational benefit
3. The task can be completed in less than 3 trivial steps
4. The task is purely conversational or informational

NOTE: You should not use this tool if there is only one trivial task to do. In this case you are better off just doing the task directly.

## Examples

### Example 1: write operation
```
User: I want to add a dark mode toggle to the application settings. Make sure you run the tests and build when you're done!
Assistant: I'll help add a dark mode toggle to your application settings. Let me create a todo list to track this implementation.
*Calls todo tool with operation="write" and todos=[
  { id: "1", content: "Create dark mode toggle component in Settings page", status: "in_progress", priority: "high" },
  { id: "2", content: "Add dark mode state management (context/store)", status: "pending", priority: "high" },
  { id: "3", content: "Implement CSS-in-JS styles for dark theme", status: "pending", priority: "medium" },
  { id: "4", content: "Update existing components to support theme switching", status: "pending", priority: "medium" },
  { id: "5", content: "Run tests and build process", status: "pending", priority: "high" }
]*
Begins working on the first task
```

### Example 2: read operation
```
User: What tasks do I have pending?
Assistant: Let me check your TODO list.
*Calls todo tool with operation="read"*
Based on your TODO list, you have the following tasks pending:
1. Create dark mode toggle component in Settings page (in_progress)
2. Add dark mode state management (pending)
3. Implement CSS-in-JS styles for dark theme (pending)
...
```

### Example 3: write operation with JSON string format
```
User: I need to add some tasks to my todo list
Assistant: I'll add those tasks to your todo list.
*Calls todo tool with operation="write" and todos='[{"id":"1","content":"New task 1","status":"pending","priority":"high"},{"id":"2","content":"New task 2","status":"pending","priority":"medium"}]'*
Tasks have been added to your todo list.
```

### Example 4: write operation with array format
```
User: Help me rename the function getCwd to getCurrentWorkingDirectory across my project
Assistant: Let me first search through your codebase to find all occurrences of 'getCwd'.
*Uses grep or search tools to locate all instances of getCwd in the codebase*
Assistant: I've found 15 instances of 'getCwd' across 8 different files. Let me create a todo list to track these changes.
*Calls todo tool with operation="write" and todos=[
  { id: "1", content: "Rename getCwd to getCurrentWorkingDirectory in src/utils.ts", status: "in_progress", priority: "high" },
  { id: "2", content: "Rename getCwd to getCurrentWorkingDirectory in src/cli.ts", status: "pending", priority: "high" },
  ...
]*
```

## Task States and Management

**Task States:**
- `pending`: Task not yet started
- `in_progress`: Currently working on (limit to ONE task at a time)
- `completed`: Task finished successfully
- `cancelled`: Task no longer needed

**Task Management:**
- Update task status in real-time as you work
- Mark tasks complete IMMEDIATELY after finishing (don't batch completions)
- Only have ONE task in_progress at any time
- Complete current tasks before starting new ones
- Cancel tasks that become irrelevant

**Task Breakdown:**
- Create specific, actionable items
- Break complex tasks into smaller, manageable steps
- Use clear, descriptive task names

## Task Item Structure

Each task item should have:
- `id`: Unique identifier (string or number)
- `content`: Description of the task (string)
- `status`: Current state ("pending", "in_progress", "completed", "cancelled")
- `priority`: Priority level (optional, "high", "medium", "low")

When in doubt, use this tool. Being proactive with task management demonstrates attentiveness and ensures you complete all requirements successfully.
