claude-task-master README

The project's README from github.com/eyaltoledano/claude-task-master. As one markdown file: README.md.

eyaltoledano%2Fclaude-task-master | Trendshift

Taskmaster logo

Taskmaster: A task management system for AI-driven development, designed to work seamlessly with any AI chat.

Discord | Docs

CI GitHub stars npm version License

NPM Downloads NPM Downloads NPM Downloads

By @eyaltoledano & @RalphEcom

Twitter Follow Twitter Follow

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

Documentation

📚 View Full Documentation

More from Hamster

Quick Install for Cursor 1.0+ (One-Click)

Add task-master-ai MCP server to Cursor

Note: After clicking the link, you'll still need to add your API keys to the configuration. The link installs the MCP server with placeholder keys that you'll need to replace with your actual API keys.

Claude Code Quick Install

For Claude Code users:

claude mcp add taskmaster-ai -- npx -y task-master-ai

Don't forget to add your API keys to the configuration:

Requirements

Taskmaster utilizes AI across several commands, and those require a separate API key. You can use a variety of models from different AI providers provided you add your API keys. For example, if you want to use Claude 3.7, you'll need an Anthropic API key.

You can define 3 types of models to be used: the main model, the research model, and the fallback model (in case either the main or research fail). Whatever model you use, its provider API key must be present in either mcp.json or .env.

At least one (1) of the following is required:

Using the research model is optional but highly recommended. You will need at least ONE API key (unless using Claude Code or Codex CLI with OAuth). Adding all API keys enables you to seamlessly switch between model providers at will.

Quick Start

MCP (Model Control Protocol) lets you run Task Master directly from your editor.

1. Add your MCP config at the following path depending on your editor

Editor Scope Linux/macOS Path Windows Path Key
Cursor Global ~/.cursor/mcp.json %USERPROFILE%\.cursor\mcp.json mcpServers
Project <project_folder>/.cursor/mcp.json <project_folder>\.cursor\mcp.json mcpServers
Windsurf Global ~/.codeium/windsurf/mcp_config.json %USERPROFILE%\.codeium\windsurf\mcp_config.json mcpServers
VS Code Project <project_folder>/.vscode/mcp.json <project_folder>\.vscode\mcp.json servers
Q CLI Global ~/.aws/amazonq/mcp.json mcpServers
Manual Configuration
Cursor & Windsurf & Q Developer CLI (mcpServers)
{
  "mcpServers": {
    "task-master-ai": {
      "command": "npx",
      "args": ["-y", "task-master-ai"],
      "env": {
        // "TASK_MASTER_TOOLS": "all", // Options: "all", "standard", "core", or comma-separated list of tools
        "ANTHROPIC_API_KEY": "YOUR_ANTHROPIC_API_KEY_HERE",
        "PERPLEXITY_API_KEY": "YOUR_PERPLEXITY_API_KEY_HERE",
        "OPENAI_API_KEY": "YOUR_OPENAI_KEY_HERE",
        "GOOGLE_API_KEY": "YOUR_GOOGLE_KEY_HERE",
        "MISTRAL_API_KEY": "YOUR_MISTRAL_KEY_HERE",
        "GROQ_API_KEY": "YOUR_GROQ_KEY_HERE",
        "OPENROUTER_API_KEY": "YOUR_OPENROUTER_KEY_HERE",
        "XAI_API_KEY": "YOUR_XAI_KEY_HERE",
        "AZURE_OPENAI_API_KEY": "YOUR_AZURE_KEY_HERE",
        "OLLAMA_API_KEY": "YOUR_OLLAMA_API_KEY_HERE"
      }
    }
  }
}

🔑 Replace YOUR_…_KEY_HERE with your real API keys. You can remove keys you don't use.

Note: If you see 0 tools enabled in the MCP settings, restart your editor and check that your API keys are correctly configured.

VS Code (servers + type)
{
  "servers": {
    "task-master-ai": {
      "command": "npx",
      "args": ["-y", "task-master-ai"],
      "env": {
        // "TASK_MASTER_TOOLS": "all", // Options: "all", "standard", "core", or comma-separated list of tools
        "ANTHROPIC_API_KEY": "YOUR_ANTHROPIC_API_KEY_HERE",
        "PERPLEXITY_API_KEY": "YOUR_PERPLEXITY_API_KEY_HERE",
        "OPENAI_API_KEY": "YOUR_OPENAI_KEY_HERE",
        "GOOGLE_API_KEY": "YOUR_GOOGLE_KEY_HERE",
        "MISTRAL_API_KEY": "YOUR_MISTRAL_KEY_HERE",
        "GROQ_API_KEY": "YOUR_GROQ_KEY_HERE",
        "OPENROUTER_API_KEY": "YOUR_OPENROUTER_KEY_HERE",
        "XAI_API_KEY": "YOUR_XAI_KEY_HERE",
        "AZURE_OPENAI_API_KEY": "YOUR_AZURE_KEY_HERE",
        "OLLAMA_API_KEY": "YOUR_OLLAMA_API_KEY_HERE"
      },
      "type": "stdio"
    }
  }
}

🔑 Replace YOUR_…_KEY_HERE with your real API keys. You can remove keys you don't use.

2. (Cursor-only) Enable Taskmaster MCP

Open Cursor Settings (Ctrl+Shift+J) ➡ Click on MCP tab on the left ➡ Enable task-master-ai with the toggle

3. (Optional) Configure the models you want to use

In your editor's AI chat pane, say:

Change the main, research and fallback models to <model_name>, <model_name> and <model_name> respectively.

For example, to use Claude Code (no API key required):

Change the main model to claude-code/sonnet

Table of available models | Claude Code setup

4. Initialize Task Master

In your editor's AI chat pane, say:

Initialize taskmaster-ai in my project

For new projects: Create your PRD at .taskmaster/docs/prd.txt. For existing projects: You can use scripts/prd.txt or migrate with task-master migrate

An example PRD template is available after initialization in .taskmaster/templates/example_prd.txt.

[!NOTE] While a PRD is recommended for complex projects, you can always create individual tasks by asking "Can you help me implement [description of what you want to do]?" in chat.

Always start with a detailed PRD.

The more detailed your PRD, the better the generated tasks will be.

6. Common Commands

Use your AI assistant to:

More examples on how to use Task Master in chat

Option 2: Using Command Line

Installation

# Install globally
npm install -g task-master-ai

# OR install locally within your project
npm install task-master-ai

Initialize a new project

# If installed globally
task-master init

# If installed locally
npx task-master init

# Initialize project with specific rules
task-master init --rules cursor,windsurf,vscode

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

Common Commands

# 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

# Show specific task(s) - supports comma-separated IDs
task-master show 1,3,5

# Research fresh information with project context
task-master research "What are the latest best practices for JWT authentication?"

# Move tasks between tags (cross-tag movement)
task-master move --from=5 --from-tag=backlog --to-tag=in-progress
task-master move --from=5,6,7 --from-tag=backlog --to-tag=done --with-dependencies
task-master move --from=5 --from-tag=backlog --to-tag=in-progress --ignore-dependencies

# Add rules after initialization
task-master rules add windsurf,roo,vscode

Tool Loading Configuration

Optimizing MCP Tool Loading

Task Master's MCP server supports selective tool loading to reduce context window usage. By default, all 36 tools are loaded (~21,000 tokens) to maintain backward compatibility with existing installations.

You can optimize performance by configuring the TASK_MASTER_TOOLS environment variable:

Available Modes

Mode Tools Context Usage Use Case
all (default) 36 ~21,000 tokens Complete feature set - all tools available
standard 15 ~10,000 tokens Common task management operations
core (or lean) 7 ~5,000 tokens Essential daily development workflow
custom Variable Variable Comma-separated list of specific tools

Configuration Methods

Method 1: Environment Variable in MCP Configuration

Add TASK_MASTER_TOOLS to your MCP configuration file's env section:

{
  "mcpServers": {  // or "servers" for VS Code
    "task-master-ai": {
      "command": "npx",
      "args": ["-y", "task-master-ai"],
      "env": {
        "TASK_MASTER_TOOLS": "standard",  // Options: "all", "standard", "core", "lean", or comma-separated list
        "ANTHROPIC_API_KEY": "your-key-here",
        // ... other API keys
      }
    }
  }
}

Method 2: Claude Code CLI (One-Time Setup)

For Claude Code users, you can set the mode during installation:

# Core mode example (~70% token reduction)
claude mcp add task-master-ai --scope user \
  --env TASK_MASTER_TOOLS="core" \
  -- npx -y task-master-ai@latest

# Custom tools example
claude mcp add task-master-ai --scope user \
  --env TASK_MASTER_TOOLS="get_tasks,next_task,set_task_status" \
  -- npx -y task-master-ai@latest

Tool Sets Details

Core Tools (7): get_tasks, next_task, get_task, set_task_status, update_subtask, parse_prd, expand_task

Standard Tools (15): All core tools plus initialize_project, analyze_project_complexity, expand_all, add_subtask, remove_task, generate, add_task, complexity_report

All Tools (36): Complete set including project setup, task management, analysis, dependencies, tags, research, and more

Recommendations

Claude Code Support

Task Master now supports Claude models through the Claude Code CLI, which requires no API key:

Learn more about Claude Code setup

Troubleshooting

If task-master init doesn't respond

Try running it with Node directly:

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

Or clone the repository and run:

git clone https://github.com/eyaltoledano/claude-task-master.git
cd claude-task-master
node scripts/init.js

Join Our Team

Join Hamster's founding team

Contributors

Task Master project contributors

Star History

Star History Chart

Licensing

Task Master is licensed under the MIT License with Commons Clause. This means you can:

✅ Allowed:

❌ Not Allowed:

See the LICENSE file for the complete license text and licensing details for more information.

claude-task-master (eyaltoledano/claude-task-master)

task-management
Searching Database…

28.2K ·GitHub
Claude-task-master
What is this?An AI-powered task-management system for AI-driven development: it turns a PRD into a structured task list your AI coding assistant works through inside Cursor, Windsurf, VS Code and similar tools.
So is it a standalone app, or does it live inside my editor?Both: it runs as an MCP server inside editors like Cursor, Windsurf, VS Code and Q CLI, and it also ships a standalone CLI you drive from the terminal.
How do I get it running?Install it globally with npm, run task-master init in your project, and put API keys in .env or mcp.json — Cursor 1.0+ users can use the one-click MCP install link instead.
Do I need an Anthropic API key to use it?Node.js 20+ and at least one provider key — Anthropic, OpenAI, Gemini, Perplexity, xAI or OpenRouter. Claude Code or Codex CLI can be used instead, with no API key.
Will its MCP tools eat my context window?All 36 tools load by default (~21,000 tokens), but setting TASKMASTERTOOLS to standard (15 tools) or core (7 tools) cuts that to about 10,000 or 5,000 tokens.
Can I use it commercially, or is the license restricted?It's MIT with the Commons Clause: you can use, modify and sell products built on it, but you can't sell Task Master itself, offer it as a hosted service, or make a competing product from it.
How does it decide which AI model to use for each job?You define up to three model roles: a main model, a research model (Perplexity is a popular pick), and a fallback in case either fails. Add several provider keys and you can switch between models at will.
What does a typical session with it actually look like?You talk to it in your editor's chat: parse a PRD into tasks, ask what's next, have it implement task 3, expand task 4 into subtasks, or run fresh research on things like JWT auth best practices for your codebase.
Do I have to write a PRD before it's useful?A PRD at .taskmaster/docs/prd.txt is recommended for complex projects — the more detailed, the better the generated tasks — but you can also just ask in chat to implement something specific. An example PRD template lands in .taskmaster/templates after init.
What are similar projects?headroom, system-prompts-and-models-of-ai-tools, overmind, ordewell, copperhead, Benzi, oracle, opencodex
Which topics is it in?windsurf-ai, ai-sdk, task-manager, cursor-ai, windsurf, task-management, openrouter, vscode, openai-compatible, cursor, gemini, anthropic
Creator
eyaltoledano
Size
28.6 MB
Stars
28.2K
Updated
CommitApr 23Release[email protected]Mar 31
Age
1y
Commits · 90 Days