Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/eyaltoledano/claude-task-master

An AI-powered task-management system you can drop into Cursor.
https://github.com/eyaltoledano/claude-task-master

ai cursor task-manager tasks tasks-list

Last synced: 7 days ago
JSON representation

An AI-powered task-management system you can drop into Cursor.

Awesome Lists containing this project

README 

        
# Task Master



### by [@eyaltoledano](https://x.com/eyaltoledano)



A task management system for AI-driven development with Claude, designed to work seamlessly with Cursor AI.



## Requirements



- Node.js 14.0.0 or higher

- Anthropic API key (Claude API)

- Anthropic SDK version 0.39.0 or higher

- OpenAI SDK (for Perplexity API integration, optional)



## Configuration



The script can be configured through environment variables in a `.env` file at the root of the project:



### Required Configuration



- `ANTHROPIC_API_KEY`: Your Anthropic API key for Claude



### Optional Configuration



- `MODEL`: Specify which Claude model to use (default: "claude-3-7-sonnet-20250219")

- `MAX_TOKENS`: Maximum tokens for model responses (default: 4000)

- `TEMPERATURE`: Temperature for model responses (default: 0.7)

- `PERPLEXITY_API_KEY`: Your Perplexity API key for research-backed subtask generation

- `PERPLEXITY_MODEL`: Specify which Perplexity model to use (default: "sonar-medium-online")

- `DEBUG`: Enable debug logging (default: false)

- `LOG_LEVEL`: Log level - debug, info, warn, error (default: info)

- `DEFAULT_SUBTASKS`: Default number of subtasks when expanding (default: 3)

- `DEFAULT_PRIORITY`: Default priority for generated tasks (default: medium)

- `PROJECT_NAME`: Override default project name in tasks.json

- `PROJECT_VERSION`: Override default version in tasks.json



## Installation



```bash

# Install globally

npm install -g task-master-ai



# OR install locally within your project

npm install task-master-ai

```



### Initialize a new project



```bash

# If installed globally

task-master init



# If installed locally

npx task-master-init

```



This will prompt you for project details and set up a new project with the necessary files and structure.



### Important Notes



1. **ES Modules Configuration:**



   - This project uses ES Modules (ESM) instead of CommonJS.

   - This is set via `"type": "module"` in your package.json.

   - Use `import/export` syntax instead of `require()`.

   - Files should use `.js` or `.mjs` extensions.

   - To use a CommonJS module, either:

     - Rename it with `.cjs` extension

     - Use `await import()` for dynamic imports

   - If you need CommonJS throughout your project, remove `"type": "module"` from package.json, but Task Master scripts expect ESM.



2. The Anthropic SDK version should be 0.39.0 or higher.



## Quick Start with Global Commands



After installing the package globally, you can use these CLI commands from any directory:



```bash

# Initialize a new project

task-master init



# Parse a PRD and generate tasks

task-master parse-prd your-prd.txt



# List all tasks

task-master list



# Show the next task to work on

task-master next



# Generate task files

task-master generate

```



## Troubleshooting



### If `task-master init` doesn't respond:



Try running it with Node directly:



```bash

node node_modules/claude-task-master/scripts/init.js

```



Or clone the repository and run:



```bash

git clone https://github.com/eyaltoledano/claude-task-master.git

cd claude-task-master

node scripts/init.js

```



## Task Structure



Tasks in tasks.json have the following structure:



- `id`: Unique identifier for the task (Example: `1`)

- `title`: Brief, descriptive title of the task (Example: `"Initialize Repo"`)

- `description`: Concise description of what the task involves (Example: `"Create a new repository, set up initial structure."`)

- `status`: Current state of the task (Example: `"pending"`, `"done"`, `"deferred"`)

- `dependencies`: IDs of tasks that must be completed before this task (Example: `[1, 2]`)

  - Dependencies are displayed with status indicators (✅ for completed, ⏱️ for pending)

  - This helps quickly identify which prerequisite tasks are blocking work

- `priority`: Importance level of the task (Example: `"high"`, `"medium"`, `"low"`)

- `details`: In-depth implementation instructions (Example: `"Use GitHub client ID/secret, handle callback, set session token."`)

- `testStrategy`: Verification approach (Example: `"Deploy and call endpoint to confirm 'Hello World' response."`)

- `subtasks`: List of smaller, more specific tasks that make up the main task (Example: `[{"id": 1, "title": "Configure OAuth", ...}]`)



## Integrating with Cursor AI



Claude Task Master is designed to work seamlessly with [Cursor AI](https://www.cursor.so/), providing a structured workflow for AI-driven development.



### Setup with Cursor



1. After initializing your project, open it in Cursor

2. The `.cursor/rules/dev_workflow.mdc` file is automatically loaded by Cursor, providing the AI with knowledge about the task management system

3. Place your PRD document in the `scripts/` directory (e.g., `scripts/prd.txt`)

4. Open Cursor's AI chat and switch to Agent mode



### Setting up MCP in Cursor



To enable enhanced task management capabilities directly within Cursor using the Model Control Protocol (MCP):



1. Go to Cursor settings

2. Navigate to the MCP section

3. Click on "Add New MCP Server"

4. Configure with the following details:

   - Name: "Task Master"

   - Type: "Command"

   - Command: "npx -y task-master-mcp"

5. Save the settings



Once configured, you can interact with Task Master's task management commands directly through Cursor's interface, providing a more integrated experience.



### Initial Task Generation



In Cursor's AI chat, instruct the agent to generate tasks from your PRD:



```

Please use the task-master parse-prd command to generate tasks from my PRD. The PRD is located at scripts/prd.txt.

```



The agent will execute:



```bash

task-master parse-prd scripts/prd.txt

```



This will:



- Parse your PRD document

- Generate a structured `tasks.json` file with tasks, dependencies, priorities, and test strategies

- The agent will understand this process due to the Cursor rules



### Generate Individual Task Files



Next, ask the agent to generate individual task files:



```

Please generate individual task files from tasks.json

```



The agent will execute:



```bash

task-master generate

```



This creates individual task files in the `tasks/` directory (e.g., `task_001.txt`, `task_002.txt`), making it easier to reference specific tasks.



## AI-Driven Development Workflow



The Cursor agent is pre-configured (via the rules file) to follow this workflow:



### 1. Task Discovery and Selection



Ask the agent to list available tasks:



```

What tasks are available to work on next?

```



The agent will:



- Run `task-master list` to see all tasks

- Run `task-master next` to determine the next task to work on

- Analyze dependencies to determine which tasks are ready to be worked on

- Prioritize tasks based on priority level and ID order

- Suggest the next task(s) to implement



### 2. Task Implementation



When implementing a task, the agent will:



- Reference the task's details section for implementation specifics

- Consider dependencies on previous tasks

- Follow the project's coding standards

- Create appropriate tests based on the task's testStrategy



You can ask:



```

Let's implement task 3. What does it involve?

```



### 3. Task Verification



Before marking a task as complete, verify it according to:



- The task's specified testStrategy

- Any automated tests in the codebase

- Manual verification if required



### 4. Task Completion



When a task is completed, tell the agent:



```

Task 3 is now complete. Please update its status.

```



The agent will execute:



```bash

task-master set-status --id=3 --status=done

```



### 5. Handling Implementation Drift



If during implementation, you discover that:



- The current approach differs significantly from what was planned

- Future tasks need to be modified due to current implementation choices

- New dependencies or requirements have emerged



Tell the agent:



```

We've changed our approach. We're now using Express instead of Fastify. Please update all future tasks to reflect this change.

```



The agent will execute:



```bash

task-master update --from=4 --prompt="Now we are using Express instead of Fastify."

```



This will rewrite or re-scope subsequent tasks in tasks.json while preserving completed work.



### 6. Breaking Down Complex Tasks



For complex tasks that need more granularity:



```

Task 5 seems complex. Can you break it down into subtasks?

```



The agent will execute:



```bash

task-master expand --id=5 --num=3

```



You can provide additional context:



```

Please break down task 5 with a focus on security considerations.

```



The agent will execute:



```bash

task-master expand --id=5 --prompt="Focus on security aspects"

```



You can also expand all pending tasks:



```

Please break down all pending tasks into subtasks.

```



The agent will execute:



```bash

task-master expand --all

```



For research-backed subtask generation using Perplexity AI:



```

Please break down task 5 using research-backed generation.

```



The agent will execute:



```bash

task-master expand --id=5 --research

```



## Command Reference



Here's a comprehensive reference of all available commands:



### Parse PRD



```bash

# Parse a PRD file and generate tasks

task-master parse-prd 



# Limit the number of tasks generated

task-master parse-prd  --num-tasks=10

```



### List Tasks



```bash

# List all tasks

task-master list



# List tasks with a specific status

task-master list --status=



# List tasks with subtasks

task-master list --with-subtasks



# List tasks with a specific status and include subtasks

task-master list --status= --with-subtasks

```



### Show Next Task



```bash

# Show the next task to work on based on dependencies and status

task-master next

```



### Show Specific Task



```bash

# Show details of a specific task

task-master show 

# or

task-master show --id=



# View a specific subtask (e.g., subtask 2 of task 1)

task-master show 1.2

```



### Update Tasks



```bash

# Update tasks from a specific ID and provide context

task-master update --from= --prompt=""

```



### Generate Task Files



```bash

# Generate individual task files from tasks.json

task-master generate

```



### Set Task Status



```bash

# Set status of a single task

task-master set-status --id= --status=



# Set status for multiple tasks

task-master set-status --id=1,2,3 --status=



# Set status for subtasks

task-master set-status --id=1.1,1.2 --status=

```



When marking a task as "done", all of its subtasks will automatically be marked as "done" as well.



### Expand Tasks



```bash

# Expand a specific task with subtasks

task-master expand --id= --num=



# Expand with additional context

task-master expand --id= --prompt=""



# Expand all pending tasks

task-master expand --all



# Force regeneration of subtasks for tasks that already have them

task-master expand --all --force



# Research-backed subtask generation for a specific task

task-master expand --id= --research



# Research-backed generation for all tasks

task-master expand --all --research

```



### Clear Subtasks



```bash

# Clear subtasks from a specific task

task-master clear-subtasks --id=



# Clear subtasks from multiple tasks

task-master clear-subtasks --id=1,2,3



# Clear subtasks from all tasks

task-master clear-subtasks --all

```



### Analyze Task Complexity



```bash

# Analyze complexity of all tasks

task-master analyze-complexity



# Save report to a custom location

task-master analyze-complexity --output=my-report.json



# Use a specific LLM model

task-master analyze-complexity --model=claude-3-opus-20240229



# Set a custom complexity threshold (1-10)

task-master analyze-complexity --threshold=6



# Use an alternative tasks file

task-master analyze-complexity --file=custom-tasks.json



# Use Perplexity AI for research-backed complexity analysis

task-master analyze-complexity --research

```



### View Complexity Report



```bash

# Display the task complexity analysis report

task-master complexity-report



# View a report at a custom location

task-master complexity-report --file=my-report.json

```



### Managing Task Dependencies



```bash

# Add a dependency to a task

task-master add-dependency --id= --depends-on=



# Remove a dependency from a task

task-master remove-dependency --id= --depends-on=



# Validate dependencies without fixing them

task-master validate-dependencies



# Find and fix invalid dependencies automatically

task-master fix-dependencies

```



### Add a New Task



```bash

# Add a new task using AI

task-master add-task --prompt="Description of the new task"



# Add a task with dependencies

task-master add-task --prompt="Description" --dependencies=1,2,3



# Add a task with priority

task-master add-task --prompt="Description" --priority=high

```



## Feature Details



### Analyzing Task Complexity



The `analyze-complexity` command:



- Analyzes each task using AI to assess its complexity on a scale of 1-10

- Recommends optimal number of subtasks based on configured DEFAULT_SUBTASKS

- Generates tailored prompts for expanding each task

- Creates a comprehensive JSON report with ready-to-use commands

- Saves the report to scripts/task-complexity-report.json by default



The generated report contains:



- Complexity analysis for each task (scored 1-10)

- Recommended number of subtasks based on complexity

- AI-generated expansion prompts customized for each task

- Ready-to-run expansion commands directly within each task analysis



### Viewing Complexity Report



The `complexity-report` command:



- Displays a formatted, easy-to-read version of the complexity analysis report

- Shows tasks organized by complexity score (highest to lowest)

- Provides complexity distribution statistics (low, medium, high)

- Highlights tasks recommended for expansion based on threshold score

- Includes ready-to-use expansion commands for each complex task

- If no report exists, offers to generate one on the spot



### Smart Task Expansion



The `expand` command automatically checks for and uses the complexity report:



When a complexity report exists:



- Tasks are automatically expanded using the recommended subtask count and prompts

- When expanding all tasks, they're processed in order of complexity (highest first)

- Research-backed generation is preserved from the complexity analysis

- You can still override recommendations with explicit command-line options



Example workflow:



```bash

# Generate the complexity analysis report with research capabilities

task-master analyze-complexity --research



# Review the report in a readable format

task-master complexity-report



# Expand tasks using the optimized recommendations

task-master expand --id=8

# or expand all tasks

task-master expand --all

```



### Finding the Next Task



The `next` command:



- Identifies tasks that are pending/in-progress and have all dependencies satisfied

- Prioritizes tasks by priority level, dependency count, and task ID

- Displays comprehensive information about the selected task:

  - Basic task details (ID, title, priority, dependencies)

  - Implementation details

  - Subtasks (if they exist)

- Provides contextual suggested actions:

  - Command to mark the task as in-progress

  - Command to mark the task as done

  - Commands for working with subtasks



### Viewing Specific Task Details



The `show` command:



- Displays comprehensive details about a specific task or subtask

- Shows task status, priority, dependencies, and detailed implementation notes

- For parent tasks, displays all subtasks and their status

- For subtasks, shows parent task relationship

- Provides contextual action suggestions based on the task's state

- Works with both regular tasks and subtasks (using the format taskId.subtaskId)



## Best Practices for AI-Driven Development



1. **Start with a detailed PRD**: The more detailed your PRD, the better the generated tasks will be.



2. **Review generated tasks**: After parsing the PRD, review the tasks to ensure they make sense and have appropriate dependencies.



3. **Analyze task complexity**: Use the complexity analysis feature to identify which tasks should be broken down further.



4. **Follow the dependency chain**: Always respect task dependencies - the Cursor agent will help with this.



5. **Update as you go**: If your implementation diverges from the plan, use the update command to keep future tasks aligned with your current approach.



6. **Break down complex tasks**: Use the expand command to break down complex tasks into manageable subtasks.



7. **Regenerate task files**: After any updates to tasks.json, regenerate the task files to keep them in sync.



8. **Communicate context to the agent**: When asking the Cursor agent to help with a task, provide context about what you're trying to achieve.



9. **Validate dependencies**: Periodically run the validate-dependencies command to check for invalid or circular dependencies.



## Example Cursor AI Interactions



### Starting a new project



```

I've just initialized a new project with Claude Task Master. I have a PRD at scripts/prd.txt.

Can you help me parse it and set up the initial tasks?

```



### Working on tasks



```

What's the next task I should work on? Please consider dependencies and priorities.

```



### Implementing a specific task



```

I'd like to implement task 4. Can you help me understand what needs to be done and how to approach it?

```



### Managing subtasks



```

I need to regenerate the subtasks for task 3 with a different approach. Can you help me clear and regenerate them?

```



### Handling changes



```

We've decided to use MongoDB instead of PostgreSQL. Can you update all future tasks to reflect this change?

```



### Completing work



```

I've finished implementing the authentication system described in task 2. All tests are passing.

Please mark it as complete and tell me what I should work on next.

```



### Analyzing complexity



```

Can you analyze the complexity of our tasks to help me understand which ones need to be broken down further?

```



### Viewing complexity report



```

Can you show me the complexity report in a more readable format?

```