Repository: eyaltoledano/claude-task-master

Stars: 26585

CLAUDE.md

Claude Code Instructions

Task Master AI Instructions

Import Task Master's development workflow commands and guidelines, treat as if import is in the main CLAUDE.md file.
@./.taskmaster/CLAUDE.md

Test Guidelines

Test File Placement

- Package & tests: Place in packages/<package-name>/src/<module>/<file>.spec.ts or apps/<app-name>/src/<module>/<file.spec.ts> alongside source
- Package integration tests: Place in packages/<package-name>/tests/integration/<module>/<file>.test.ts or apps/<app-name>/tests/integration/<module>/<file>.test.ts alongside source
- Isolated unit tests: Use tests/unit/packages/<package-name>/ only when parallel placement isn't possible
- Test extension: Always use .ts for TypeScript tests, never .js

Synchronous Tests

- NEVER use async/await in test functions unless testing actual asynchronous operations
- Use synchronous top-level imports instead of dynamic await import()
- Test bodies should be synchronous whenever possible
- Example:

typescript

// ✅ CORRECT - Synchronous imports with .ts extension
  import { MyClass } from '../src/my-class.js';
  it('should verify behavior', () => {
    expect(new MyClass().property).toBe(value);
  });  // ❌ INCORRECT - Async imports
  it('should verify behavior', async () => {
    const { MyClass } = await import('../src/my-class.js');
    expect(new MyClass().property).toBe(value);
  });

When to Write Tests

ALWAYS write tests for:

- Bug fixes: Add a regression test that would have caught the bug
- Business logic: Complex calculations, validations, transformations
- Edge cases: Boundary conditions, error handling, null/undefined cases
- Public APIs: Methods other code depends on
- Integration points: Database, file system, external APIs

SKIP tests for:

- Simple getters/setters: getX() { return this.x; }
- Trivial pass-through functions with no logic
- Pure configuration objects
- Code that just delegates to another tested function

Examples:

javascript

// ✅ WRITE A TEST - Bug fix with regression prevention
it('should use correct baseURL from defaultBaseURL config', () => {
  const provider = new ZAIProvider();
  expect(provider.defaultBaseURL).toBe('https://api.z.ai/api/paas/v4/');
});
// ✅ WRITE A TEST - Business logic with edge cases
it('should parse subtask IDs correctly', () => {
  expect(parseTaskId('1.2.3')).toEqual({ taskId: 1, subtaskId: 2, subSubtaskId: 3 });
  expect(parseTaskId('invalid')).toBeNull();
});
// ❌ SKIP TEST - Trivial getter
class Task {
  get id() { return this._id; } // No test needed
}// ❌ SKIP TEST - Pure delegation
function getTasks() {
  return taskManager.getTasks(); // Already tested in taskManager
}

Bug Fix Workflow:

1. Encounter a bug
2. Write a failing test that reproduces it
3. Fix the bug
4. Verify test now passes
5. Commit both fix and test together

Testing Guidelines

Principles: FIRST (Fast, Independent, Repeatable, Self-validating, Timely)
Structure: AAA (Arrange, Act, Assert)
Coverage: Right-BICEP (Right results, Boundary, Inverse, Cross-check, Error conditions, Performance)

#### What to Mock

Unit tests (.spec.ts - test single unit in isolation):
- @tm/core: Mock only external I/O (Supabase, APIs, filesystem). Use real internal services.
- apps/cli: Mock tm-core responses. Use real Commander/chalk/inquirer/other npm packages (test display logic).
- apps/mcp: Mock tm-core responses. Use real MCP framework (test response formatting).

Integration tests (tests/integration/ - test multiple units together):
- All packages: Use real tm-core, mock only external boundaries (APIs, DB, filesystem).

Never mock:
- Internal utilities/helpers in the same package
- Standard frameworks (Commander, Express) - let them run
- Standard library

Rule of thumb: Mock what you're NOT testing. CLI unit tests test display → mock tm-core. Core unit tests test logic → mock I/O. Integration tests test full flow → mock only external APIs.

Red flag: Mocking 3+ dependencies in a unit test means code is doing too much or is in the wrong layer.

Anti-pattern: Heavily mocked tests don't verify real behavior—they verify that you wired up mocks correctly. You end up writing orchestration code to satisfy tests, rather than tests that validate your actual implementation. If testing is hard, move the logic to where it's naturally testable.

Architecture Guidelines

Business Logic Separation

CRITICAL RULE: ALL business logic must live in @tm/core, NOT in presentation layers.

- @tm/core (packages/tm-core/):
- Contains ALL business logic, domain models, services, and utilities
- Provides clean facade APIs through domain objects (tasks, auth, workflow, git, config)
- Houses all complexity - parsing, validation, transformations, calculations, etc.
- Example: Task ID parsing, subtask extraction, status validation, dependency resolution

- @tm/cli (apps/cli/):
- Thin presentation layer ONLY
- Calls tm-core methods and displays results
- Handles CLI-specific concerns: argument parsing, output formatting, user prompts
- NO business logic, NO data transformations, NO calculations

- @tm/mcp (apps/mcp/):
- Thin presentation layer ONLY
- Calls tm-core methods and returns MCP-formatted responses
- Handles MCP-specific concerns: tool schemas, parameter validation, response formatting
- NO business logic, NO data transformations, NO calculations

- apps/extension (future):
- Thin presentation layer ONLY
- Calls tm-core methods and displays in VS Code UI
- NO business logic

Examples of violations to avoid:

- ❌ Creating helper functions in CLI/MCP to parse task IDs → Move to tm-core
- ❌ Data transformation logic in CLI/MCP → Move to tm-core
- ❌ Validation logic in CLI/MCP → Move to tm-core
- ❌ Duplicating logic across CLI and MCP → Implement once in tm-core

Correct approach:

- ✅ Add method to TasksDomain: tasks.get(taskId) (automatically handles task and subtask IDs)
- ✅ CLI calls: await tmCore.tasks.get(taskId) (supports "1", "1.2", "HAM-123", "HAM-123.2")
- ✅ MCP calls: await tmCore.tasks.get(taskId) (same intelligent ID parsing)
- ✅ Single source of truth in tm-core

Code Quality & Reusability Guidelines

Apply standard software engineering principles:

- DRY (Don't Repeat Yourself): Extract patterns that appear 2+ times into reusable components or utilities
- YAGNI (You Aren't Gonna Need It): Don't over-engineer. Create abstractions when duplication appears, not before
- Maintainable: Single source of truth. Change once, update everywhere
- Readable: Clear naming, proper structure, export from index files
- Flexible: Accept configuration options with sensible defaults

Documentation Guidelines

- Documentation location: Write docs in apps/docs/ (Mintlify site source), not docs/
- Documentation URL: Reference docs at <https://docs.task-master.dev>, not local file paths

Changeset Guidelines

- Add a changeset for code changes - Run npx changeset after making code changes (not needed for docs-only PRs)
- When creating changesets, remember that it's user-facing, meaning we don't have to get into the specifics of the code, but rather mention what the end-user is getting or fixing from this changeset
- Run npm run turbo:typecheck before pushing to ensure TypeScript type checks pass
- Run npm run test -w <package-name> to test a package

README.md

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

By @eyaltoledano & @RalphEcom

![Twitter Follow](https://x.com/eyaltoledano)
![Twitter Follow](https://x.com/RalphEcom)

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

Documentation

📚 View Full Documentation

For detailed guides, API references, and comprehensive examples, visit our documentation site.

Quick Reference

The following documentation is also available in the docs directory:

- Configuration Guide - Set up environment variables and customize Task Master
- Tutorial - Step-by-step guide to getting started with Task Master
- Command Reference - Complete list of all available commands
- Task Structure - Understanding the task format and features
- Example Interactions - Common Cursor AI interaction examples
- Migration Guide - Guide to migrating to the new project structure

#### Quick Install for Cursor 1.0+ (One-Click)

![Add task-master-ai MCP server to Cursor](https://cursor.com/en/install-mcp?name=task-master-ai&config=eyJjb21tYW5kIjoibnB4IC15IC0tcGFja2FnZT10YXNrLW1hc3Rlci1haSB0YXNrLW1hc3Rlci1haSIsImVudiI6eyJBTlRIUk9QSUNfQVBJX0tFWSI6IllPVVJfQU5USFJPUElDX0FQSV9LRVlfSEVSRSIsIlBFUlBMRVhJVFlfQVBJX0tFWSI6IllPVVJfUEVSUExFWElUWV9BUElfS0VZX0hFUkUiLCJPUEVOQUlfQVBJX0tFWSI6IllPVVJfT1BFTkFJX0tFWV9IRVJFIiwiR09PR0xFX0FQSV9LRVkiOiJZT1VSX0dPT0dMRV9LRVlfSEVSRSIsIk1JU1RSQUxfQVBJX0tFWSI6IllPVVJfTUlTVFJBTF9LRVlfSEVSRSIsIkdST1FfQVBJX0tFWSI6IllPVVJfR1JPUV9LRVlfSEVSRSIsIk9QRU5ST1VURVJfQVBJX0tFWSI6IllPVVJfT1BFTlJPVVRFUl9LRVlfSEVSRSIsIlhBSV9BUElfS0VZIjoiWU9VUl9YQUlfS0VZX0hFUkUiLCJBWlVSRV9PUEVOQUlfQVBJX0tFWSI6IllPVVJfQVpVUkVfS0VZX0hFUkUiLCJPTExBTUFfQVBJX0tFWSI6IllPVVJfT0xMQU1BX0FQSV9LRVlfSEVSRSJ9fQ%3D%3D)

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:

bash

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

Don't forget to add your API keys to the configuration:
- in the root .env of your Project
- in the "env" section of your mcp config for taskmaster-ai

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:

- Anthropic API key (Claude API)
- OpenAI API key
- Google Gemini API key
- Perplexity API key (for research model)
- xAI API Key (for research or main model)
- OpenRouter API Key (for research or main model)
- Claude Code (no API key required - requires Claude Code CLI)
- Codex CLI (OAuth via ChatGPT subscription - requires Codex CLI)

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

Option 1: MCP (Recommended)

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)

json

{
  "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)

json

{
  "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:

txt

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):

txt

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:

txt

Initialize taskmaster-ai in my project

#### 5. Make sure you have a PRD (Recommended)

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:

- Parse requirements: Can you parse my PRD at scripts/prd.txt?
- Plan next step: What's the next task I should work on?
- Implement a task: Can you help me implement task 3?
- View multiple tasks: Can you show me tasks 1, 3, and 5?
- Expand a task: Can you help me expand task 4?
- Research fresh information: Research the latest best practices for implementing JWT authentication with Node.js
- Research with context: Research React Query v5 migration strategies for our current API implementation in src/api.js

More examples on how to use Task Master in chat

Option 2: Using Command Line

#### 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
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

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
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:

jsonc

{
  "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:

bash

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

- New users: Start with "standard" mode for a good balance
- Large projects: Use "core" mode to minimize token usage
- Complex workflows: Use "all" mode or custom selection
- Backward compatibility: If not specified, defaults to "all" mode

Claude Code Support

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

- Models: claude-code/opus and claude-code/sonnet
- Requirements: Claude Code CLI installed
- Benefits: No API key needed, uses your local Claude instance

Learn more about Claude Code setup

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

Join Our Team

Contributors

Star History

![Star History Chart](https://www.star-history.com/#eyaltoledano/claude-task-master&Timeline)

Licensing

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

✅ Allowed:

- Use Task Master for any purpose (personal, commercial, academic)
- Modify the code
- Distribute copies
- Create and sell products built using Task Master

❌ Not Allowed:

- Sell Task Master itself
- Offer Task Master as a hosted service
- Create competing products based on Task Master

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

Repository: eyaltoledano/claude-task-master

Stars: 26585

CLAUDE.md Copy Chapter

Claude Code Instructions

Task Master AI Instructions Copy Chapter

Test Guidelines Copy Chapter

Test File Placement Copy Section

Synchronous Tests Copy Section

When to Write Tests Copy Section

Testing Guidelines Copy Section

Architecture Guidelines Copy Chapter

Business Logic Separation Copy Section

Code Quality & Reusability Guidelines Copy Chapter

Documentation Guidelines Copy Chapter

Changeset Guidelines Copy Chapter

README.md Copy Chapter

By @eyaltoledano & @RalphEcom @eyaltoledano & @RalphEcom')" title="Copy chapter prompt for LLMs"> Copy Chapter

Documentation Copy Chapter

Quick Reference Copy Section

Requirements Copy Chapter

Quick Start Copy Chapter

Option 1: MCP (Recommended) Copy Section

Option 2: Using Command Line Copy Section

Install globally

OR install locally within your project

If installed globally

If installed locally

Initialize project with specific rules

Initialize a new project

Parse a PRD and generate tasks

List all tasks

Show the next task to work on

Show specific task(s) - supports comma-separated IDs

Research fresh information with project context

Move tasks between tags (cross-tag movement)

Add rules after initialization

Tool Loading Configuration Copy Chapter

Optimizing MCP Tool Loading Copy Section

Available Modes Copy Section

Configuration Methods Copy Section

Core mode example (~70% token reduction)

Custom tools example

Tool Sets Details Copy Section

Recommendations Copy Section

Claude Code Support Copy Chapter

Troubleshooting Copy Chapter

If task-master init doesn't respond task-master init doesn't respond')" title="Copy section prompt for LLMs"> Copy Section

Join Our Team Copy Chapter

Contributors Copy Chapter

Star History Copy Chapter

Licensing Copy Chapter

CLAUDE.md

Task Master AI Instructions

Test Guidelines

Test File Placement

Synchronous Tests

When to Write Tests

Testing Guidelines

Architecture Guidelines

Business Logic Separation

Code Quality & Reusability Guidelines

Documentation Guidelines

Changeset Guidelines

README.md

By @eyaltoledano & @RalphEcom

Documentation

Quick Reference

Requirements

Quick Start

Option 1: MCP (Recommended)

Option 2: Using Command Line

Tool Loading Configuration

Optimizing MCP Tool Loading

Available Modes

Configuration Methods

Tool Sets Details

Recommendations

Claude Code Support

Troubleshooting

If `task-master init` doesn't respond

Join Our Team

Contributors

Star History

Licensing