claude-task-master Documentation

1. Project Overview & Quickstart (eyaltoledano/claude-task-master) Copy Chapter

File: README.md Copy Chapter

By [@eyaltoledano](https://x.com/eyaltoledano) & [@RalphEcom](https://x.com/RalphEcom) Copy Chapter

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

Documentation Copy Chapter

📚 View Full Documentation

Quick Links Copy Section

• Quick Start Guide
• Installation
• API Keys & Providers
• Supported Editors
• MCP Tools Reference
• CLI Commands Reference
• Task Structure
• Task Dependencies
• Tags & Workstreams
• Research Command
• Loop Command
• AI Providers Overview
• Team Collaboration
• Best Practices
• FAQ
• Changelog

More from Hamster Copy Section

• Hamster Studio
• Product & Engineering Methods
• Product & Engineering Skills
• Hamster Pricing

Quick Install for Cursor 1.0+ (One-Click)

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:

• in the root .env of your Project
• in the "env" section of your mcp config for taskmaster-ai

Requirements Copy Chapter

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 Copy Chapter

Option 1: MCP (Recommended) Copy Section

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

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

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 Copy Section

Installation

# Install globally
npm install 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 Copy Chapter

Optimizing MCP Tool Loading Copy Section

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 Copy Section

Configuration Methods Copy Section

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 Copy Section

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 Copy Section

• 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 Copy Chapter

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 Copy Chapter

If `task-master init` doesn't respond Copy Section

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 Copy Chapter

Contributors Copy Chapter

Star History Copy Chapter

Licensing Copy Chapter

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.

File: apps/mcp/src/tools/README-ZOD-V3.md Copy Chapter

Why MCP Tools Use Zod v3

Problem Copy Chapter

• FastMCP uses xsschema to convert schemas → outputs JSON Schema Draft 2020-12
• MCP clients (Augment IDE, gemini-cli, etc.) only support Draft-07
• Using Zod v4 in tools causes "vendor undefined" errors and tool discovery failures

Temporary Solution Copy Chapter

All MCP tool files import from zod/v3 instead of zod:

import { z } from 'zod/v3';  // ✅ Draft-07 compatible
// NOT: import { z } from 'zod';  // ❌ Would use Draft 2020-12

Why This Works Copy Section

• Zod v4 ships with v3 compatibility at zod/v3
• FastMCP + zod-to-json-schema converts Zod v3 schemas → Draft-07
• This ensures MCP clients can discover and use our tools

What This Means Copy Section

• ✅ MCP tools → use zod/v3 (apps/mcp & mcp-server/src/tools)
• ✅ Rest of codebase → uses zod (Zod v4)
• ✅ No conflicts → they're from the same package, just different versions

When Can We Remove This? Copy Chapter

This workaround can be removed when either:

1. FastMCP adds JSON Schema version configuration

   • e.g., new FastMCP({ jsonSchema: { target: 'draft-07' } })
   • Tracking: https://github.com/punkpeye/fastmcp/issues/189

2. MCP spec adds Draft 2020-12 support

   • Unlikely in the short term

3. xsschema adds version targeting

   • Would allow FastMCP to use Draft-07

How to Maintain Copy Chapter

When adding new MCP tools:

// ✅ CORRECT
import { z } from 'zod/v3';

export function registerMyTool(server: FastMCP) {
  server.addTool({
    name: 'my_tool',
    parameters: z.object({ ... }),  // Will use Draft-07
    execute: async (args, context) => { ... }
  });
}

// ❌ WRONG - Will break MCP client compatibility
import { z } from 'zod';  // Don't do this in apps/mcp/src/tools/

Last Updated: 2025-10-18
Affects: All files in apps/mcp/src/tools/
See Also: mcp-server/src/tools/README-ZOD-V3.md (same workaround)

File: apps/extension/docs/extension-CI-setup.md Copy Chapter

VS Code Extension CI/CD Setup

This document explains the CI/CD setup for the Task Master VS Code extension using automated changesets.

🔄 Workflows Overview Copy Chapter

1. Extension CI (`extension-ci.yml`) Copy Section

Triggers

• Push to main or next branches (only when extension files change)
• Pull requests to main or next (only when extension files change)

What it does

• ✅ Lints and type-checks the extension code
• 🔨 Builds the extension (npm run build)
• 📦 Creates a clean package (npm run package)
• 🧪 Runs tests with VS Code test framework
• 📋 Creates a test VSIX package to verify packaging works
• 💾 Uploads build artifacts for inspection

2. Version & Publish (`version.yml`) Copy Section

Triggers:

• Push to main branch

What it does:

• 🔍 Detects changeset files for pending releases
• 📝 Creates "Version Packages" PR with updated versions and CHANGELOG
• 🤖 When Version PR is merged, automatically:
  • 🔨 Builds and packages the extension
  • 🏷️ Creates git tags with changeset automation
  • 📤 Publishes to VS Code Marketplace
  • 🌍 Publishes to Open VSX Registry
  • 📊 Updates package versions and CHANGELOG

🚀 Changeset Workflow Copy Chapter

Creating Changes Copy Section

When making changes to the extension:

1. Make your code changes
2. Create a changeset:
   bash Copy

   # From project root
   npx changeset add

3. Select the extension package: Choose taskr-kanban when prompted
4. Select version bump type:
   • patch: Bug fixes, minor updates
   • minor: New features, backwards compatible
   • major: Breaking changes
5. Write a summary: Describe what changed for users
6. Commit changeset file along with your code changes
7. Push to feature branch and create PR

Automated Publishing Process Copy Section

1. PR with changeset gets merged to main
2. Version workflow detects changesets and creates "Version Packages" PR
3. Review and merge the Version PR
4. Automated publishing happens immediately:
   • Extension is built using 3-file packaging system
   • VSIX package is created and tested
   • Published to VS Code Marketplace (if VSCE_PAT is set)
   • Published to Open VSX Registry (if OVSX_PAT is set)
   • Git tags are created: [email protected]
   • CHANGELOG is updated automatically

🔑 Required Secrets Copy Chapter

To use the automated publishing, you need to set up these GitHub repository secrets:

`VSCE_PAT` (VS Code Marketplace Personal Access Token) Copy Section

1. Go to Azure DevOps
2. Sign in with your Microsoft account
3. Create a Personal Access Token:
   • Name: VS Code Extension Publishing
   • Organization: All accessible organizations
   • Expiration: Custom (recommend 1 year)
   • Scopes: Custom defined → Marketplace → Manage
4. Copy the token and add it to GitHub Secrets as VSCE_PAT

`OVSX_PAT` (Open VSX Registry Personal Access Token) Copy Section

1. Go to Open VSX Registry
2. Sign in with your GitHub account
3. Go to your User Settings
4. Create a new Access Token:
   • Description: VS Code Extension Publishing
   • Scopes: Leave default (full access)
5. Copy the token and add it to GitHub Secrets as OVSX_PAT

`GITHUB_TOKEN` (automatically provided) Copy Section

This is automatically available in GitHub Actions - no setup required.

📋 Version Management Copy Chapter

Changeset-Based Versioning Copy Section

Versions are automatically managed by changesets:

• No manual version updates needed - changesets handle this automatically
• Semantic versioning is enforced based on changeset types
• Changelog generation happens automatically
• Git tagging is handled by the automation

Critical Fields Sync Copy Section

The automation ensures these fields stay in sync between package.json and package.publish.json:

{
  "version": "1.0.2",                    // ✅ AUTO-SYNCED
  "publisher": "Hamster",        // ⚠️ MUST MATCH MANUALLY
  "displayName": "taskr: Task Master Kanban", // ⚠️ MUST MATCH MANUALLY
  "description": "...",                  // ⚠️ MUST MATCH MANUALLY
  "engines": { "vscode": "^1.93.0" },   // ⚠️ MUST MATCH MANUALLY
  "categories": [...],                   // ⚠️ MUST MATCH MANUALLY
  "contributes": { ... }                 // ⚠️ MUST MATCH MANUALLY
}

Note: Only version is automatically synced. Other fields must be manually kept in sync.

🔍 Monitoring Builds Copy Chapter

CI Status Copy Section

• Green ✅: Extension builds and tests successfully
• Red ❌: Build/test failures - check logs for details
• Yellow 🟡: Partial success - some jobs may have warnings

Version PR Status Copy Section

• Version PR Created: Changesets detected, review and merge to publish
• No Version PR: No changesets found, no releases pending
• Version PR Merged: Automated publishing triggered

Release Status Copy Section

• Published 🎉: Extension live on VS Code Marketplace and Open VSX
• Skipped ℹ️: No changesets found, no release needed
• Failed ❌: Check logs - often missing secrets or build issues

Artifacts Copy Section

Workflows upload artifacts that you can download:

• CI: Test results, built files, and VSIX package
• Version: Final VSIX package and published extension

🛠️ Troubleshooting Copy Chapter

Common Issues Copy Section

No Version PR Created

• Check: Changeset files exist in .changeset/ directory
• Check: Changeset refers to taskr-kanban package name
• Check: Changes were pushed to main branch
• Solution: Create changeset with npx changeset add

Version PR Not Publishing

• Check: Version PR was actually merged (not just closed)
• Check: Required secrets (VSCE_PAT, OVSX_PAT) are set
• Check: No build failures in workflow logs
• Solution: Re-run workflow or check secret configuration

`VSCE_PAT` is not set Error

• Ensure VSCE_PAT secret is added to repository
• Check token hasn't expired
• Verify token has Marketplace → Manage permissions

`OVSX_PAT` is not set Error

• Ensure OVSX_PAT secret is added to repository
• Check token hasn't expired
• Verify you're signed in to Open VSX Registry with GitHub

Build Failures

• Check extension code compiles locally: cd apps/extension && npm run build
• Verify tests pass locally: npm run test
• Check for TypeScript errors: npm run typecheck

Packaging Failures

• Ensure clean package builds: npm run package
• Check vsix-build structure is correct
• Verify package.publish.json has correct repository field

Changeset Issues

• Wrong package name: Ensure changeset refers to taskr-kanban
• Invalid format: Check changeset markdown format is correct
• Merge conflicts: Resolve any conflicts in changeset files

📁 File Structure Impact Copy Chapter

The CI workflows respect the 3-file packaging system:

• Development: Uses package.json for dependencies and scripts
• Release: Uses package.publish.json for clean marketplace package
• Build: Uses package.mjs to create vsix-build/ for final packaging
• Changesets: Automatically manage versions across the system

🌍 Dual Registry Publishing Copy Chapter

Your extension will be automatically published to both:

• VS Code Marketplace - For official VS Code users
• Open VSX Registry - For Cursor, Windsurf, VSCodium, Gitpod, Eclipse Theia, and other compatible editors

🎯 Benefits of Changeset Automation Copy Chapter

• ✅ Automated versioning: No manual version bumps needed
• ✅ Generated changelogs: Automatic, accurate release notes
• ✅ Semantic versioning: Enforced through changeset types
• ✅ Git tagging: Proper tags for extension releases
• ✅ Conflict prevention: Clear separation of extension vs. main package versions
• ✅ Review process: Version changes are reviewable via PR
• ✅ Rollback capability: Easy to revert if issues arise

This ensures clean, predictable, and fully automated publishing to both registries! 🚀

File: apps/extension/docs/extension-development-guide.md Copy Chapter

VS Code Extension Development Guide

📁 File Structure Overview Copy Chapter

This VS Code extension uses a 3-file packaging system to avoid dependency conflicts during publishing:

apps/extension/
├── package.json           # Development configuration
├── package.publish.json   # Clean publishing configuration  
├── package.mjs           # Build script for packaging
├── .vscodeignore         # Files to exclude from extension package
└── vsix-build/           # Generated clean package directory

📋 File Purposes Copy Chapter

`package.json` (Development) Copy Section

• Purpose: Development environment with all build tools
• Contains:
  • All devDependencies needed for building
  • Development scripts (build, watch, lint, etc.)
  • Development package name: "taskr"
• Used for: Local development, building, testing

`package.publish.json` (Publishing) Copy Section

• Purpose: Clean distribution version for VS Code Marketplace
• Contains:
  • No devDependencies (avoids dependency conflicts)
  • Publishing metadata (keywords, repository, categories)
  • Marketplace package name: "taskr-kanban"
  • VS Code extension configuration
• Used for: Final extension packaging

`package.mjs` (Build Script) Copy Section

• Purpose: Creates clean package for distribution
• Process:
  1. Builds the extension (build:js + build:css)
  2. Creates clean vsix-build/ directory
  3. Copies only essential files (no source code)
  4. Renames package.publish.json → package.json
  5. Ready for vsce package

🚀 Development Workflow Copy Chapter

Local Development Copy Section

# Install dependencies
npm install

# Start development with hot reload
npm run watch

# Run just JavaScript build
npm run build:js

# Run just CSS build  
npm run build:css

# Full production build
npm run build

# Type checking
npm run typecheck

# Linting
npm run lint

Testing in VS Code Copy Section

1. Press F5 in VS Code to launch Extension Development Host
2. Test your extension functionality in the new window
3. Use Developer: Reload Window to reload after changes

📦 Production Packaging Copy Chapter

Step 1: Build Clean Package Copy Section

npm run package

This creates vsix-build/ with clean distribution files.

Step 2: Create VSIX Copy Section

cd vsix-build
npx vsce package --no-dependencies

Creates: taskr-kanban-1.0.1.vsix

Alternative: One Command Copy Section

npm run package && cd vsix-build && npx vsce package --no-dependencies

🔄 Keeping Files in Sync Copy Chapter

Critical Fields to Sync Between Files Copy Section

When updating extension metadata, ensure these fields match between package.json and package.publish.json:

Version & Identity

{
  "version": "1.0.1",                    // ⚠️ MUST MATCH
  "publisher": "Hamster",        // ⚠️ MUST MATCH  
  "displayName": "taskr: Task Master Kanban", // ⚠️ MUST MATCH
  "description": "A visual Kanban board...",  // ⚠️ MUST MATCH
}

VS Code Configuration

{
  "engines": { "vscode": "^1.101.0" },   // ⚠️ MUST MATCH
  "categories": [...],                    // ⚠️ MUST MATCH
  "activationEvents": [...],              // ⚠️ MUST MATCH
  "main": "./dist/extension.js",          // ⚠️ MUST MATCH
  "contributes": { ... }                  // ⚠️ MUST MATCH EXACTLY
}

Key Differences (Should NOT Match) Copy Section

// package.json (dev)
{
  "name": "taskr",                       // ✅ Short dev name
  "devDependencies": { ... },            // ✅ Only in dev file
  "scripts": { ... }                     // ✅ Build scripts
}

// package.publish.json (publishing)
{
  "name": "taskr-kanban",               // ✅ Marketplace name
  "keywords": [...],                     // ✅ Only in publish file
  "repository": "https://github.com/...", // ✅ Only in publish file
  // NO devDependencies                  // ✅ Clean for publishing
  // NO build scripts                    // ✅ Not needed in package
}

🤖 Automated Release Process Copy Chapter

Changesets Workflow Copy Section

This extension uses Changesets for automated version management and publishing.

Adding Changes

When making changes to the extension:

1. Make your code changes
2. Create a changeset:
   bash Copy

   # From project root
   npx changeset add

3. Select the extension package: Choose taskr-kanban when prompted
4. Select version bump type:
   • patch: Bug fixes, minor updates
   • minor: New features, backwards compatible
   • major: Breaking changes
5. Write a summary: Describe what changed for users

Automated Publishing

The automation workflow runs on pushes to main:

1. Version Workflow (.github/workflows/version.yml):

   • Detects when changesets exist
   • Creates a "Version Packages" PR with updated versions and CHANGELOG
   • When the PR is merged, automatically publishes the extension

2. Release Process (scripts/release.sh):

   • Builds the extension using the 3-file packaging system
   • Creates VSIX package
   • Publishes to VS Code Marketplace (if VSCE_PAT is set)
   • Publishes to Open VSX Registry (if OVSX_PAT is set)
   • Creates git tags for the extension version

Required Secrets

For automated publishing, these secrets must be set in the repository:

• VSCE_PAT: Personal Access Token for VS Code Marketplace
• OVSX_PAT: Personal Access Token for Open VSX Registry
• GITHUB_TOKEN: Automatically provided by GitHub Actions

Manual Release

If needed, you can manually trigger a release:

# From project root
./scripts/release.sh

Extension Tagging Copy Section

The extension uses a separate tagging strategy from the main package:

• Extension tags: [email protected]
• Main package tags: [email protected]

This allows independent versioning and prevents conflicts in the monorepo.

🔍 Troubleshooting Copy Chapter

Dependency Conflicts Copy Section

Problem: vsce package fails with missing dependencies
Solution: Use the 3-file system - never run vsce package from root

Build Failures Copy Section

Problem: Extension not working after build
Check:

1. All files copied to vsix-build/dist/
2. package.publish.json has correct main field
3. VS Code engine version compatibility

Sync Issues Copy Section

Problem: Extension works locally but fails when packaged
Check: Ensure critical fields are synced between package files

Changeset Issues Copy Section

Problem: Version workflow not triggering
Check:

1. Changeset files exist in .changeset/
2. Package name in changeset matches package.publish.json
3. Changes are pushed to main branch

Problem: Publishing fails
Check:

1. Required secrets are set in repository settings
2. package.publish.json has correct repository URL
3. Build process completes successfully

📝 Version Release Checklist Copy Chapter

Manual Releases Copy Section

1. Create changeset: npx changeset add
2. Update critical fields in both package.json and package.publish.json
3. Test locally with F5 in VS Code
4. Commit and push to trigger automated workflow

Automated Releases (Recommended) Copy Section

1. Create changeset: npx changeset add
2. Push to feature branch and create PR
3. Merge PR - this triggers version PR creation
4. Review and merge version PR - this triggers automated publishing

🎯 Why This System? Copy Chapter

• Avoids dependency conflicts: VS Code doesn't see dev dependencies
• Clean distribution: Only essential files in final package
• Faster packaging: No dependency resolution during vsce package
• Maintainable: Clear separation of dev vs. production configs
• Reliable: Consistent, conflict-free packaging process
• Automated: Changesets handle versioning and publishing automatically
• Traceable: Clear changelog and git tags for every release

Remember: Always use npx changeset add for changes, then push to trigger automated releases! 🚀

File: apps/extension/README.md Copy Chapter

Official Taskmaster AI Extension

Transform your AI-driven development workflow with a beautiful, interactive Kanban board directly in VS Code. Seamlessly manage tasks from Taskmaster AI projects with real-time synchronization and intelligent task management.

🎯 What is Taskmaster AI? Copy Chapter

Taskmaster AI is an intelligent task management system designed for AI-assisted development. It helps you break down complex projects into manageable tasks, track progress, and leverage AI to enhance your development workflow.

✨ Key Features Copy Chapter

📊 **Interactive Kanban Board** Copy Section

• Drag & Drop Interface - Effortlessly move tasks between status columns
• Real-time Sync - Changes instantly reflect in your Taskmaster project files
• Multiple Views - Board view and detailed task sidebar
• Smart Columns - Pending, In Progress, Review, Done, Deferred, and Cancelled

🤖 **AI-Powered Features** Copy Section

• Task Content Generation - Regenerate task descriptions using AI
• Smart Task Updates - Append findings and progress notes automatically
• MCP Integration - Seamless connection to Taskmaster AI via Model Context Protocol
• Intelligent Caching - Smart performance optimization with background refresh

🚀 **Performance & Usability** Copy Section

• Offline Support - Continue working even when disconnected
• Auto-refresh - Automatic polling for task changes with smart frequency
• VS Code Native - Perfectly integrated with VS Code themes and UI
• Modern Interface - Built with ShadCN UI components and Tailwind CSS

🛠️ Installation Copy Chapter

Prerequisites Copy Section

1. VS Code 1.90.0 or higher
2. Node.js 20.0 or higher (for Taskmaster MCP server)

Install the Extension Copy Section

1. From VS Code Marketplace:
   • Click the Install button above
   • The extension will be automatically added to your VS Code instance

🚀 Quick Start Copy Chapter

1. **Initialize Taskmaster Project** Copy Section

If you don't have a Taskmaster project yet:

cd your-project
npm i task-master-ai
   task-master init

2. **Open Kanban Board** Copy Section

• Command Palette (Ctrl+Shift+P): Taskmaster Kanban: Show Board
• Or the extension automatically activates when you have a .taskmaster folder in your workspace

3. **MCP Server Setup** Copy Section

The extension automatically handles the Taskmaster MCP server connection:

• No manual installation required - The extension spawns the MCP server automatically
• Uses npx by default - Automatically downloads Taskmaster AI when needed
• Configurable - You can customize the MCP server command in settings if needed

4. **Start Managing Tasks** Copy Section

• Drag tasks between columns to change status
• Click tasks to view detailed information
• Use AI features to enhance task content
• Add subtasks with the + button on parent tasks

📋 Usage Guide Copy Chapter

Task Management Copy Section

Understanding Task Statuses Copy Section

• 📋 Pending - Tasks ready to be started
• 🚀 In Progress - Currently being worked on
• 👀 Review - Awaiting review or feedback
• ✅ Done - Completed tasks
• ⏸️ Deferred - Postponed for later

**AI-Powered Task Management** Copy Section

The extension integrates seamlessly with Taskmaster AI via MCP to provide:

• Smart Task Generation - AI creates detailed implementation plans
• Progress Tracking - Append timestamped notes and findings
• Content Enhancement - Regenerate task descriptions for clarity
• Research Integration - Get up-to-date information for your tasks

⚙️ Configuration Copy Chapter

Access settings via File → Preferences → Settings and search for "Taskmaster":

**MCP Connection Settings** Copy Section

• MCP Server Command - Path to task-master-ai executable (default: npx)
• MCP Server Args - Arguments for the server command (default: -y, task-master-ai)
• Connection Timeout - Server response timeout (default: 30s)
• Auto Refresh - Enable automatic task updates (default: enabled)

**UI Preferences** Copy Section

• Theme - Auto, Light, or Dark mode
• Show Completed Tasks - Display done tasks in board (default: enabled)
• Task Display Limit - Maximum tasks to show (default: 100)

**Performance Options** Copy Section

• Cache Duration - How long to cache task data (default: 5s)
• Concurrent Requests - Max simultaneous API calls (default: 5)

🔧 Troubleshooting Copy Chapter

**Extension Not Loading** Copy Section

1. Ensure Node.js 20+ is installed
2. Check workspace contains .taskmaster folder
3. Restart VS Code
4. Check Output panel (View → Output → Taskmaster Kanban)

**MCP Connection Issues** Copy Section

1. Command not found: Ensure Node.js and npx are in your PATH
2. Timeout errors: Increase timeout in settings
3. Permission errors: Check Node.js permissions
4. Network issues: Verify internet connection for npx downloads

**Tasks Not Updating** Copy Section

1. Check MCP connection status in status bar
2. Verify .taskmaster/tasks/tasks.json exists
3. Try manual refresh: Taskmaster Kanban: Check Connection
4. Review error logs in Output panel

**Performance Issues** Copy Section

1. Reduce task display limit in settings
2. Increase cache duration
3. Disable auto-refresh if needed
4. Close other VS Code extensions temporarily

🆘 Support & Resources Copy Chapter

**Getting Help** Copy Section

• 📖 Documentation: Taskmaster AI Docs
• 🐛 Report Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 🐛 Report Issues: GitHub Issues

🎯 Tips for Best Results Copy Chapter

**Project Organization** Copy Section

• Use descriptive task titles
• Add detailed implementation notes
• Set appropriate task dependencies
• Leverage AI features for complex tasks

**Workflow Optimization** Copy Section

• Review task details before starting work
• Use subtasks for complex features
• Update task status as you progress
• Add findings and learnings to task notes

**Collaboration** Copy Section

• Keep task descriptions updated
• Use consistent status conventions
• Document decisions in task details
• Share knowledge through task notes

🏆 Why Taskmaster Kanban? Copy Chapter

✅ Visual workflow management for your Taskmaster projects
✅ AI-powered task enhancement built right in
✅ Real-time synchronization keeps everything in sync
✅ Native VS Code integration feels like part of the editor
✅ Free and open source with active development

Transform your development workflow today! 🚀

Originally Made with ❤️ by David Maliglowka

Support Copy Chapter

This is an open-source project maintained in my spare time. While I strive to fix bugs and improve the extension, support is provided on a best-effort basis. Feel free to:

• Report issues on GitHub
• Submit pull requests with improvements
• Fork the project if you need specific modifications

Disclaimer Copy Chapter

This extension is provided "as is" without any warranties. Use at your own risk. The author is not responsible for any issues, data loss, or damages that may occur from using this extension. Please backup your work regularly and test thoroughly before using in important projects.

File: apps/docs/capabilities/cli-root-commands.mdx Copy Chapter

title: CLI Commands sidebarTitle: "CLI Commands" Copy Chapter

# Limit the number of tasks generated
task-master parse-prd  --num-tasks=10
```

# List tasks with a specific status
task-master list --status=<status>

# List tasks with subtasks
task-master list --with-subtasks

# List tasks with a specific status and include subtasks
task-master list --status=<status> --with-subtasks

# Watch for changes and auto-refresh the list
task-master list --watch
task-master list -w

# Combine watch with other options
task-master list all -w              # Watch all tasks with subtasks
task-master list -w --compact        # Watch in compact format
task-master list --status=pending -w # Watch pending tasks only
```

# View a specific subtask (e.g., subtask 2 of task 1)
task-master show 1.2
```

# Use research-backed updates with Perplexity AI
task-master update-task --id= --prompt="" --research
```

# Example: Add details about API rate limiting to subtask 2 of task 5
task-master update-subtask --id=5.2 --prompt="Add rate limiting of 100 requests per minute"

# Use research-backed updates with Perplexity AI
task-master update-subtask --id= --prompt="" --research
```

Unlike the `update-task` command which replaces task information, the `update-subtask` command _appends_ new information to the existing subtask details, marking it with a timestamp. This is useful for iteratively enhancing subtasks while preserving the original content.

# Set status for multiple tasks
task-master set-status --id=1,2,3 --status=<status>

# Set status for subtasks
task-master set-status --id=1.1,1.2 --status=<status>
```

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

# Expand with additional context
task-master expand --id= --prompt="<context>"

# 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 from multiple tasks
task-master clear-subtasks --id=1,2,3

# Clear subtasks from all tasks
task-master clear-subtasks --all
```

# 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 your configured research model for research-backed complexity analysis
task-master analyze-complexity --research
```

# View a report at a custom location
task-master complexity-report --file=my-report.json
```

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

File: apps/docs/capabilities/index.mdx Copy Chapter

title: Technical Capabilities sidebarTitle: "Technical Capabilities" Copy Chapter

Capabilities (Technical)

Discover the technical capabilities of Task Master, including supported models, integrations, and more.

CLI Interface Synopsis

This document outlines the command-line interface (CLI) for the Task Master application, as defined in bin/task-master.js and the scripts/modules/commands.js file (which I will assume exists based on the context). This guide is intended for those writing user-facing documentation to understand how users interact with the application from the command line.

Entry Point Copy Chapter

The main entry point for the CLI is the task-master command, which is an executable script that spawns the main application logic in scripts/dev.js.

Global Options Copy Chapter

The following options are available for all commands:

• -h, --help: Display help information.
• --version: Display the application's version.

Commands Copy Chapter

The CLI is organized into a series of commands, each with its own set of options. The following is a summary of the available commands, categorized by their functionality.

1. Task and Subtask Management Copy Section

• add: Creates a new task using an AI-powered prompt.
  • --prompt : The prompt to use for generating the task.
  • --dependencies <dependencies>: A comma-separated list of task IDs that this task depends on.
  • --priority : The priority of the task (e.g., high, medium, low).
• add-subtask: Adds a subtask to a parent task.
  • --parent-id : The ID of the parent task.
  • --task-id <taskId>: The ID of an existing task to convert to a subtask.
  • --title <title>: The title of the new subtask.
• remove: Removes one or more tasks or subtasks.
  • --ids : A comma-separated list of task or subtask IDs to remove.
• remove-subtask: Removes a subtask from its parent.
  • --id <subtaskId>: The ID of the subtask to remove (in the format parentId.subtaskId).
  • --convert-to-task: Converts the subtask to a standalone task.
• update: Updates multiple tasks starting from a specific ID.
  • --from <fromId>: The ID of the task to start updating from.
  • --prompt : The new context to apply to the tasks.
• update-task: Updates a single task.
  • --id <taskId>: The ID of the task to update.
  • --prompt : The new context to apply to the task.
• update-subtask: Appends information to a subtask.
  • --id <subtaskId>: The ID of the subtask to update (in the format parentId.subtaskId).
  • --prompt : The information to append to the subtask.
• move: Moves a task or subtask.
  • --from : The ID of the task or subtask to move.
  • --to <destinationId>: The destination ID.
• clear-subtasks: Clears all subtasks from one or more tasks.
  • --ids : A comma-separated list of task IDs.

2. Task Information and Status Copy Section

• list: Lists all tasks.
  • --status <status>: Filters tasks by status.
  • --with-subtasks: Includes subtasks in the list.
• show: Shows the details of a specific task.
  • --id <taskId>: The ID of the task to show.
• next: Shows the next task to work on.
• set-status: Sets the status of a task or subtask.
  • --id : The ID of the task or subtask.
  • --status <status>: The new status.

3. Task Analysis and Expansion Copy Section

• parse-prd: Parses a PRD to generate tasks.
  • --file <file>: The path to the PRD file.
  • --num-tasks <numTasks>: The number of tasks to generate.
• expand: Expands a task into subtasks.
  • --id <taskId>: The ID of the task to expand.
  • --num-subtasks <numSubtasks>: The number of subtasks to generate.
• expand-all: Expands all eligible tasks.
  • --num-subtasks <numSubtasks>: The number of subtasks to generate for each task.
• analyze-complexity: Analyzes task complexity.
  • --file <file>: The path to the tasks file.
• complexity-report: Displays the complexity analysis report.

4. Project and Configuration Copy Section

• init: Initializes a new project.
• generate: Generates individual task files.
• migrate: Migrates a project to the new directory structure.
• research: Performs AI-powered research.
  • --query <query>: The research query.

This synopsis provides a comprehensive overview of the CLI commands and their options, which should be helpful for creating user-facing documentation.

Core Implementation Synopsis

This document provides a high-level overview of the core implementation of the Task Master application, focusing on the functionalities exposed through scripts/modules/task-manager.js. This serves as a guide for understanding the application's capabilities when writing user-facing documentation.

Core Concepts Copy Chapter

The application revolves around the management of tasks and subtasks, which are stored in a tasks.json file. The core logic provides functionalities to create, read, update, and delete tasks and subtasks, as well as manage their dependencies and statuses.

Task Structure Copy Section

A task is a JSON object with the following key properties:

• id: A unique number identifying the task.
• title: A string representing the task's title.
• description: A string providing a brief description of the task.
• details: A string containing detailed information about the task.
• testStrategy: A string describing how to test the task.
• status: A string representing the task's current status (e.g., pending, in-progress, done).
• dependencies: An array of task IDs that this task depends on.
• priority: A string representing the task's priority (e.g., high, medium, low).
• subtasks: An array of subtask objects.

A subtask has a similar structure to a task but is nested within a parent task.

Feature Categories Copy Chapter

The core functionalities can be categorized as follows:

1. Task and Subtask Management Copy Section

These functions are the bread and butter of the application, allowing for the creation, modification, and deletion of tasks and subtasks.

• addTask(prompt, dependencies, priority): Creates a new task using an AI-powered prompt to generate the title, description, details, and test strategy. It can also be used to create a task manually by providing the task data directly.
• addSubtask(parentId, existingTaskId, newSubtaskData): Adds a subtask to a parent task. It can either convert an existing task into a subtask or create a new subtask from scratch.
• removeTask(taskIds): Removes one or more tasks or subtasks.
• removeSubtask(subtaskId, convertToTask): Removes a subtask from its parent. It can optionally convert the subtask into a standalone task.
• updateTaskById(taskId, prompt): Updates a task's information based on a prompt.
• updateSubtaskById(subtaskId, prompt): Appends additional information to a subtask's details.
• updateTasks(fromId, prompt): Updates multiple tasks starting from a specific ID based on a new context.
• moveTask(sourceId, destinationId): Moves a task or subtask to a new position.
• clearSubtasks(taskIds): Clears all subtasks from one or more tasks.

2. Task Information and Status Copy Section

These functions are used to retrieve information about tasks and manage their status.

• listTasks(statusFilter, withSubtasks): Lists all tasks, with options to filter by status and include subtasks.
• findTaskById(taskId): Finds a task by its ID.
• taskExists(taskId): Checks if a task with a given ID exists.
• setTaskStatus(taskIdInput, newStatus): Sets the status of a task or subtask.
  -al
• updateSingleTaskStatus(taskIdInput, newStatus): A helper function to update the status of a single task or subtask.
• findNextTask(): Determines the next task to work on based on dependencies and status.

3. Task Analysis and Expansion Copy Section

These functions leverage AI to analyze and break down tasks.

• parsePRD(prdPath, numTasks): Parses a Product Requirements Document (PRD) to generate an initial set of tasks.
• expandTask(taskId, numSubtasks): Expands a task into a specified number of subtasks using AI.
• expandAllTasks(numSubtasks): Expands all eligible pending or in-progress tasks.
• analyzeTaskComplexity(options): Analyzes the complexity of tasks and generates recommendations for expansion.
• readComplexityReport(): Reads the complexity analysis report.

4. Dependency Management Copy Section

These functions are crucial for managing the relationships between tasks.

• isTaskDependentOn(task, targetTaskId): Checks if a task has a direct or indirect dependency on another task.

5. Project and Configuration Copy Section

These functions are for managing the project and its configuration.

• generateTaskFiles(): Generates individual task files from tasks.json.
• migrateProject(): Migrates the project to the new .taskmaster directory structure.
• performResearch(query, options): Performs AI-powered research with project context.

This overview should provide a solid foundation for creating user-facing documentation. For more detailed information on each function, refer to the source code in scripts/modules/task-manager/.

MCP Interface Synopsis

This document provides an overview of the MCP (Machine-to-Machine Communication Protocol) interface for the Task Master application. The MCP interface is defined in the mcp-server/ directory and exposes the application's core functionalities as a set of tools that can be called remotely.

Core Concepts Copy Chapter

The MCP interface is built on top of the fastmcp library and registers a set of tools that correspond to the core functionalities of the Task Master application. These tools are defined in the mcp-server/src/tools/ directory and are registered with the MCP server in mcp-server/src/tools/index.js.

Each tool is defined with a name, a description, and a set of parameters that are validated using the zod library. The execute function of each tool calls the corresponding core logic function from scripts/modules/task-manager.js.

Tool Categories Copy Chapter

The MCP tools can be categorized in the same way as the core functionalities:

1. Task and Subtask Management Copy Section

• add_task: Creates a new task.
• add_subtask: Adds a subtask to a parent task.
• remove_task: Removes one or more tasks or subtasks.
• remove_subtask: Removes a subtask from its parent.
• update_task: Updates a single task.
• update_subtask: Appends information to a subtask.
• update: Updates multiple tasks.
• move_task: Moves a task or subtask.
• clear_subtasks: Clears all subtasks from one or more tasks.

2. Task Information and Status Copy Section

• get_tasks: Lists all tasks.
• get_task: Shows the details of a specific task.
• next_task: Shows the next task to work on.
• set_task_status: Sets the status of a task or subtask.

3. Task Analysis and Expansion Copy Section

• parse_prd: Parses a PRD to generate tasks.
• expand_task: Expands a task into subtasks.
• expand_all: Expands all eligible tasks.
• analyze_project_complexity: Analyzes task complexity.
• complexity_report: Displays the complexity analysis report.

4. Dependency Management Copy Section

• add_dependency: Adds a dependency to a task.
• remove_dependency: Removes a dependency from a task.
• validate_dependencies: Validates the dependencies of all tasks.
• fix_dependencies: Fixes any invalid dependencies.

5. Project and Configuration Copy Section

• initialize_project: Initializes a new project.
• generate: Generates individual task files.
• models: Manages AI model configurations.
• research: Performs AI-powered research.

6. Tag Management Copy Section

• add_tag: Creates a new tag.
• delete_tag: Deletes a tag.
• list_tags: Lists all tags.
• use_tag: Switches to a different tag.
• rename_tag: Renames a tag.
• copy_tag: Copies a tag.

This synopsis provides a clear overview of the MCP interface and its available tools, which will be valuable for anyone writing documentation for developers who need to interact with the Task Master application programmatically.

File: apps/docs/capabilities/loop.mdx Copy Chapter

title: Loop Command sidebarTitle: "Loop Command" Copy Chapter

Loop Command

The loop command runs Claude Code in autonomous loops, spawning fresh agent sessions for each iteration. This approach, known as the "Ralph Wiggum pattern" (credited to Jeffrey Huntley, popularized by Matt Pocock), maintains context quality by avoiding long-running sessions that accumulate context fatigue.

Overview Copy Chapter

Instead of a single long-running agent session that degrades over time, the loop command:

1. Spawns fresh sessions - Each iteration starts with a clean context
2. Uses preset prompts - Built-in or custom prompts guide each iteration
3. Tracks progress - A progress file persists notes across sessions
4. Detects completion - Special markers signal when work is done or blocked

This pattern is ideal for batch operations like clearing task backlogs, improving test coverage, or fixing lint errors across a codebase.

Basic Usage Copy Chapter

Run 10 iterations with the default task-completion preset:

task-master loop -n 10

Run 5 iterations with the test-coverage preset:

task-master loop -n 5 --prompt test-coverage

Run iterations with a custom prompt file:

task-master loop -n 10 --prompt ./my-custom-prompt.md

Filter to specific task tag:

task-master loop -n 10 --tag backend

How It Works Copy Chapter

Each loop iteration:

1. Generates a prompt combining context header + preset content
2. Spawns claude -p as a fresh subprocess
3. Captures output and checks for completion markers
4. Appends progress notes to the progress file
5. Sleeps before the next iteration (configurable)

The loop exits early when:

• An agent outputs <loop-complete>REASON</loop-complete> - all work done
• An agent outputs <loop-blocked>REASON</loop-blocked> - cannot proceed
• Maximum iterations reached

Progress File Copy Chapter

Each iteration's agent has access to a shared progress file (default: .taskmaster/loop-progress.txt) via the @ file reference syntax. Agents append notes about what they completed, allowing subsequent iterations to build on previous work.

Example progress file content:

# Loop Progress - Started 2025-01-09 10:30:00
# Preset: test-coverage | Iterations: 10

[10:30:45] Iteration 1 (Task 5.2): Added unit tests for UserService
[10:35:22] Iteration 2 (Task 5.3): Added integration tests for auth flow
[10:40:18] Iteration 3: All pending test tasks complete

CLI Options Copy Chapter

Option Details Copy Section

--prompt accepts two types of values:

• Preset names: Use built-in presets like default, test-coverage, linting, duplication, or entropy
• File paths: Provide a path to a custom prompt file (e.g., ./my-custom-loop.md)

--on-complete runs only on success:
The shell command only executes when finalStatus is all_complete, meaning an agent output the <loop-complete> marker. It does not run on max_iterations, blocked, or error outcomes.

Built-in Presets Copy Chapter

The loop command includes five built-in presets for common development workflows. Each preset guides agents to complete ONE focused task per iteration.

default Copy Section

The standard task completion workflow. Agents work through your Task Master backlog, completing one task per iteration.

task-master loop -n 10 --prompt default

What it does:

1. Runs task-master next to get the highest priority available task
2. Reads task details with task-master show
3. Implements the task with the smallest possible change
4. Runs tests and type checks to verify quality
5. Marks the task complete with task-master set-status --id= --status=done
6. Commits work with a descriptive message

Completion criteria: All pending tasks are complete.

test-coverage Copy Section

Improves test coverage by writing meaningful tests for user-facing behavior - not just chasing coverage numbers.

task-master loop -n 10 --prompt test-coverage

What it does:

1. Runs the coverage command (npm run coverage, etc.)
2. Identifies the most important user-facing feature lacking tests
3. Writes ONE meaningful test validating real behavior
4. Verifies coverage increased as a side effect
5. Commits with message: test(<file>): <describe user behavior tested>

Philosophy: Don't write tests just to increase coverage. Use coverage as a guide to find untested user-facing behavior. Prioritize error handling, CLI commands, API endpoints, and file parsing over internal utilities.

Completion criteria: Coverage reaches target or 100%.

linting Copy Section

Cleans up lint errors and type errors systematically, one fix per iteration.

task-master loop -n 20 --prompt linting

What it does:

1. Runs lint command (npm run lint, eslint ., etc.)
2. Runs type check (tsc --noEmit, etc.)
3. Picks ONE error to fix, prioritizing:
   • Type errors (breaks builds)
   • Security-related lint errors
   • Errors in frequently-changed files
4. Fixes with minimal changes - no surrounding refactoring
5. Commits with message: fix(<file>): <describe error fixed>

Completion criteria: Zero lint errors and zero type errors.

duplication Copy Section

Finds duplicated code using detection tools and refactors into shared utilities.

task-master loop -n 10 --prompt duplication

What it does:

1. Runs duplication detection (npx jscpd . or similar)
2. Reviews the report and picks ONE clone to refactor, prioritizing:
   • Larger clones (more lines = more maintenance burden)
   • Clones in frequently-changed files
   • Clones with slight variations
3. Extracts duplicated code into a shared utility
4. Updates all clone locations to use the shared utility
5. Runs tests to verify behavior is preserved

Completion criteria: Duplication below threshold (e.g., <3%).

entropy Copy Section

Targets code smells that increase cognitive load and maintenance burden.

task-master loop -n 10 --prompt entropy

Code smells targeted:

• Long functions (>60 lines) → extract into smaller functions
• Deep nesting (>3 levels) → use early returns, extract conditions
• Large files (>500 lines) → split into focused modules
• Magic numbers → extract into named constants
• Complex conditionals → extract into well-named functions
• God classes → split responsibilities

What it does:

1. Scans codebase for code smells (uses judgment or tools like complexity-report)
2. Picks ONE smell to fix, prioritizing smells in critical paths
3. Refactors with minimal changes - no over-engineering
4. Runs tests to verify behavior is preserved

Completion criteria: No significant code smells remain.

Custom Prompts Copy Chapter

You can create custom prompt files for specialized workflows that aren't covered by the built-in presets.

Specifying a Custom Prompt Copy Section

Pass the file path to the --prompt option:

task-master loop -n 10 --prompt ./my-custom-loop.md

The path can be absolute or relative to the current directory.

Required Structure Copy Section

Custom prompts should follow this structure to work effectively with the loop system:

# Your Loop Title

Brief description of what this loop does.

## Files Available

- @.taskmaster/tasks/tasks.json - Your task backlog
- @.taskmaster/loop-progress.txt - Progress log from previous iterations
- @path/to/other/file.ts - Any other files the agent needs

## Process

1. Step one of the workflow
2. Step two of the workflow
3. ... more steps

## Important

- Complete ONLY ONE task per session
- Keep changes small and focused
- Do NOT start another task after completing one
- If work is complete, output: <loop-complete>REASON</loop-complete>
- If blocked, output: <loop-blocked>REASON</loop-blocked>

File References with @ Syntax Copy Section

The @ prefix makes files available to the agent. Claude Code will read these files when processing the prompt:

## Files Available

- @src/index.ts - Main entry point
- @package.json - Dependencies and scripts
- @.taskmaster/loop-progress.txt - Progress from previous iterations

Without the @ prefix, file paths are just text. With @, the agent can actually read and reference the file contents.

Completion Markers Copy Section

The loop watches for two special markers in agent output:

When either marker is detected, the loop exits early. The reason text is captured in the final result.

Example usage in a custom prompt:

## Important

- If all migrations are complete, output: <loop-complete>MIGRATIONS_DONE</loop-complete>
- If a migration fails with an unrecoverable error, output: <loop-blocked>MIGRATION_FAILED: describe error</loop-blocked>

Best Practices Copy Section

1. Be specific: Clearly define what "done" means for your workflow
2. One task per iteration: Instruct agents to complete exactly one unit of work
3. Use the progress file: Reference @.taskmaster/loop-progress.txt so agents can see what previous iterations accomplished
4. Include quality checks: Add steps for running tests or type checks before completing
5. Define completion criteria: Tell agents exactly when to output <loop-complete>
6. Handle edge cases: Define when to output <loop-blocked> to avoid infinite loops

Progress File Copy Chapter

The progress file is a shared log that persists notes across loop iterations. Since each iteration spawns a fresh agent session, this file provides continuity.

Default Location Copy Section

.taskmaster/loop-progress.txt

Override with the --progress-file option:

task-master loop -n 10 --progress-file ./my-progress.txt

How It Works Copy Section

1. Initialization: The loop creates the progress file at the start with a header
2. Each iteration: Agents read the file via @ reference and append notes about their work
3. Context continuity: Subsequent agents see what previous iterations accomplished

File Format Copy Section

The progress file uses a simple timestamped format:

# Loop Progress - Started 2025-01-09 10:30:00
# Preset: default | Iterations: 10 | Tag: backend

[10:30:45] Iteration 1 (Task 5.2): Implemented user authentication endpoint
[10:35:22] Iteration 2 (Task 5.3): Added input validation for login form
[10:40:18] Iteration 3 (Task 5.4): Fixed edge case in token refresh logic
[10:45:01] Iteration 4: All pending backend tasks complete

Format breakdown:

• Header: Timestamp, preset name, max iterations, optional tag filter
• Entries: [HH:MM:SS] Iteration N (Task ID): Description
• Task ID: Optional - included when agent worked on a specific task

Using Progress in Custom Prompts Copy Section

Always include the progress file in your ## Files Available section:

## Files Available

- @.taskmaster/loop-progress.txt - Progress log from previous iterations

And instruct agents to append notes:

## Process

...
7. Append a brief note to the progress file about what was done

This creates a chain of context that helps each iteration build on previous work.

Real-World Examples Copy Chapter

Here are practical scenarios for using the loop command in your development workflow.

Weekend Automation Copy Section

Run a loop overnight or over the weekend to clear your task backlog while you're away:

task-master loop -n 50 --prompt default --on-complete 'notify-send "Loop complete!"'

This runs up to 50 iterations, completing tasks one by one. When all tasks are done, you'll get a desktop notification.

Test Coverage Sprint Copy Section

Push your test coverage from 60% to 80% systematically:

task-master loop -n 20 --prompt test-coverage --on-complete 'echo "Coverage target reached!"'

Each iteration identifies the most important untested user-facing behavior and writes a meaningful test. The agent prioritizes error handling, API endpoints, and CLI commands over internal utilities.

Tech Debt Day Copy Section

Dedicate a day to cleaning up lint errors across your codebase:

task-master loop -n 30 --prompt linting --sleep 3

With --sleep 3, iterations run faster for quick fixes. The agent systematically addresses type errors first (they break builds), then security-related lint errors, then others.

Code Review Prep Copy Section

Reduce code duplication before opening a PR:

task-master loop -n 10 --prompt duplication --tag backend

The --tag backend flag focuses the loop on backend code only. Each iteration finds and refactors one instance of duplicated code into a shared utility.

Multi-Tag Workflow Copy Section

Process different parts of your codebase in sequence:

# First, handle critical backend tasks
task-master loop -n 10 --tag backend --status pending

# Then, address frontend tasks
task-master loop -n 10 --tag frontend --status pending

Custom Migration Script Copy Section

For complex migrations, create a custom prompt and run it:

# Create custom-migration.md with your specific steps
task-master loop -n 20 --prompt ./custom-migration.md --progress-file ./migration-progress.txt

Use a separate progress file to track migration-specific notes.

File: apps/docs/capabilities/mcp.mdx Copy Chapter

title: MCP Tools sidebarTitle: "MCP Tools" Copy Chapter

MCP Tools

This document provides an overview of the MCP (Machine-to-Machine Communication Protocol) interface for the Task Master application. The MCP interface is defined in the mcp-server/ directory and exposes the application's core functionalities as a set of tools that can be called remotely.

Core Concepts Copy Chapter

The MCP interface is built on top of the fastmcp library and registers a set of tools that correspond to the core functionalities of the Task Master application. These tools are defined in the mcp-server/src/tools/ directory and are registered with the MCP server in mcp-server/src/tools/index.js.

Each tool is defined with a name, a description, and a set of parameters that are validated using the zod library. The execute function of each tool calls the corresponding core logic function from scripts/modules/task-manager.js.

Configurable Tool Loading Copy Chapter

To optimize LLM context usage, you can control which Task Master MCP tools are loaded using the TASK_MASTER_TOOLS environment variable. This is particularly useful when working with LLMs that have context limits or when you only need a subset of tools.

Configuration Modes Copy Section

Core Tools (Default, Lean Mode)

Loads only 7 essential tools for daily development. Ideal for minimal context usage.

Core tools included:

• get_tasks - List all tasks
• next_task - Find the next task to work on
• get_task - Get detailed task information
• set_task_status - Update task status
• update_subtask - Add implementation notes
• parse_prd - Generate tasks from PRD
• expand_task - Break down tasks into subtasks

{
  "mcpServers": {
    "task-master-ai": {
      "command": "npx",
      "args": ["-y", "task-master-ai"],
      "env": {
        "TASK_MASTER_TOOLS": "core",
        "ANTHROPIC_API_KEY": "your_key_here"
      }
    }
  }
}

You can also use "lean" as an alias for "core". If TASK_MASTER_TOOLS is not set, core tools are loaded by default.

Standard Tools

Loads 15 commonly used tools. Balances functionality with context efficiency.

Standard tools include all core tools plus:

• initialize_project - Set up new projects
• analyze_project_complexity - Analyze task complexity
• expand_all - Expand all eligible tasks
• add_subtask - Add subtasks manually
• remove_task - Remove tasks
• generate - Generate task markdown files
• add_task - Create new tasks
• complexity_report - View complexity analysis

{
  "mcpServers": {
    "task-master-ai": {
      "command": "npx",
      "args": ["-y", "task-master-ai"],
      "env": {
        "TASK_MASTER_TOOLS": "standard",
        "ANTHROPIC_API_KEY": "your_key_here"
      }
    }
  }
}

Custom Tool Selection

Specify exactly which tools to load using a comma-separated list. Tool names are case-insensitive and support both underscores and hyphens.

{
  "mcpServers": {
    "task-master-ai": {
      "command": "npx",
      "args": ["-y", "task-master-ai"],
      "env": {
        "TASK_MASTER_TOOLS": "get_tasks,next_task,set_task_status,update_subtask",
        "ANTHROPIC_API_KEY": "your_key_here"
      }
    }
  }
}

All Tools

Loads all 36 available tools. Use when you need full Task Master functionality.

{
  "mcpServers": {
    "task-master-ai": {
      "command": "npx",
      "args": ["-y", "task-master-ai"],
      "env": {
        "TASK_MASTER_TOOLS": "all",
        "ANTHROPIC_API_KEY": "your_key_here"
      }
    }
  }
}

Choosing the Right Configuration Copy Section

• Use core/lean: Default setting, ideal for basic task management workflows or when context limits are strict
• Use standard: For most development workflows that include task creation and analysis
• Use all: When you need full functionality including tag management, dependencies, and advanced features
• Use custom list: When you have specific tool requirements or want to experiment with minimal sets

Verification Copy Section

When the MCP server starts, it logs which tools were loaded:

Task Master MCP Server starting...
Tool mode configuration: standard
Loading standard tools
Registering 15 MCP tools (mode: standard)
Successfully registered 15/15 tools

Tool Categories Copy Chapter

The MCP tools can be categorized in the same way as the core functionalities:

1. Task and Subtask Management Copy Section

• add_task: Creates a new task.
• add_subtask: Adds a subtask to a parent task.
• remove_task: Removes one or more tasks or subtasks.
• remove_subtask: Removes a subtask from its parent.
• update_task: Updates a single task.
• update_subtask: Appends information to a subtask.
• update: Updates multiple tasks.
• move_task: Moves a task or subtask.
• clear_subtasks: Clears all subtasks from one or more tasks.

2. Task Information and Status Copy Section

• get_tasks: Lists all tasks.
• get_task: Shows the details of a specific task.
• next_task: Shows the next task to work on.
• set_task_status: Sets the status of a task or subtask.

3. Task Analysis and Expansion Copy Section

• parse_prd: Parses a PRD to generate tasks.
• expand_task: Expands a task into subtasks.
• expand_all: Expands all eligible tasks.
• analyze_project_complexity: Analyzes task complexity.
• complexity_report: Displays the complexity analysis report.

4. Dependency Management Copy Section

• add_dependency: Adds a dependency to a task.
• remove_dependency: Removes a dependency from a task.
• validate_dependencies: Validates the dependencies of all tasks.
• fix_dependencies: Fixes any invalid dependencies.

5. Project and Configuration Copy Section

• initialize_project: Initializes a new project.
• generate: Generates individual task files.
• models: Manages AI model configurations.
• research: Performs AI-powered research.

6. Tag Management Copy Section

• add_tag: Creates a new tag.
• delete_tag: Deletes a tag.
• list_tags: Lists all tags.
• use_tag: Switches to a different tag.
• rename_tag: Renames a tag.
• copy_tag: Copies a tag.

File: apps/docs/capabilities/rpg-method.mdx Copy Chapter

title: RPG Method for PRD Creation sidebarTitle: "RPG Method" Copy Chapter

Repository Planning Graph (RPG) Method

The RPG (Repository Planning Graph) method is an advanced approach to creating Product Requirements Documents that generate highly-structured, dependency-aware task graphs. It's based on Microsoft Research's methodology for scalable codebase generation.

When to Use RPG Copy Chapter

Use the RPG template (example_prd_rpg.md) for:

• Complex multi-module systems with intricate dependencies
• Large-scale codebases being built from scratch
• Projects requiring explicit architecture and clear module boundaries
• Teams needing dependency visibility for parallel development

For simpler features or smaller projects, the standard example_prd.md template may be more appropriate.

Core Principles Copy Chapter

1. Dual-Semantics Copy Section

Separate functional thinking (WHAT) from structural thinking (HOW):

Functional: "Data Validation capability with schema checking and rule enforcement"
                    ↓
Structural: "src/validation/ with schema-validator.js and rule-validator.js"

This separation prevents mixing concerns and creates clearer module boundaries.

2. Explicit Dependencies Copy Section

Never assume dependencies - always state them explicitly:

Good:
  Module: data-ingestion
  Depends on: [schema-validator, config-manager]

Bad:
  Module: data-ingestion
  (Assumes schema-validator exists somewhere)

Explicit dependencies enable:

• Topological ordering of implementation
• Parallel development of independent modules
• Clear build/test order
• Early detection of circular dependencies

3. Topological Order Copy Section

Build foundation layers before higher layers:

Phase 0 (Foundation): error-handling, base-types, config
                ↓
Phase 1 (Data): validation, ingestion (depend on Phase 0)
                ↓
Phase 2 (Core): algorithms, pipelines (depend on Phase 1)
                ↓
Phase 3 (API): routes, handlers (depend on Phase 2)

Task Master automatically orders tasks based on this dependency chain.

4. Progressive Refinement Copy Section

Start broad, refine iteratively:

1. High-level capabilities → Main tasks
2. Features per capability → Subtasks
3. Implementation details → Expanded subtasks

Template Structure Copy Chapter

The RPG template guides you through 7 key sections:

1. Overview Copy Section

• Problem statement
• Target users
• Success metrics

2. Functional Decomposition (WHAT) Copy Section

• High-level capability domains
• Features per capability
• Inputs/outputs/behavior for each feature

Example:

Capability: Data Management
  Feature: Schema validation
    Inputs: JSON object, schema definition
    Outputs: Validation result + error details
    Behavior: Iterate fields, check types, enforce constraints

3. Structural Decomposition (HOW) Copy Section

• Repository folder structure
• Module-to-capability mapping
• File organization
• Public interfaces/exports

Example:

Capability: Data Management
  → Maps to: src/data/
    ├── schema-validator.js    (Schema validation feature)
    ├── rule-validator.js      (Rule validation feature)
    └── index.js               (Exports)

4. Dependency Graph (CRITICAL) Copy Section

• Foundation layer (no dependencies)
• Each subsequent layer's dependencies
• Explicit "depends on" declarations

Example:

Foundation Layer (Phase 0):
  - error-handling: No dependencies
  - base-types: No dependencies

Data Layer (Phase 1):
  - schema-validator: Depends on [base-types, error-handling]
  - data-ingestion: Depends on [schema-validator]

5. Implementation Roadmap Copy Section

• Phases with entry/exit criteria
• Tasks grouped by phase
• Clear deliverables per phase

6. Test Strategy Copy Section

• Test pyramid ratios
• Coverage requirements
• Critical test scenarios per module
• Guidelines for test generation

7. Architecture & Risks Copy Section

• Technical architecture
• Data models
• Technology decisions
• Risk mitigation strategies

Using RPG with Task Master Copy Chapter

Step 1: Create PRD with RPG Template Copy Section

Use a code-context-aware tool to fill out the template:

# In Claude Code, Cursor, or similar
"Create a PRD using @.taskmaster/templates/example_prd_rpg.txt for [your project]"

Why code context matters: The AI needs to understand your existing codebase to make informed decisions about:

• Module boundaries
• Dependency relationships
• Integration points
• Naming conventions

Recommended tools:

• Claude Code (claude-code CLI)
• Cursor/Windsurf
• Gemini CLI (large contexts)
• Codex/Grok CLI

Step 2: Parse PRD into Tasks Copy Section

task-master parse-prd .taskmaster/docs/your-prd.md --research

Task Master will:

1. Extract capabilities → Main tasks
2. Extract features → Subtasks
3. Parse dependencies → Task dependencies
4. Order by phases → Task priorities

Result: A dependency-aware task graph ready for topological execution.

Step 3: Analyze Complexity Copy Section

task-master analyze-complexity --research

Review the complexity report to identify tasks that need expansion.

Step 4: Expand Tasks Copy Section

task-master expand --all --research

Break down complex tasks into manageable subtasks while preserving dependency chains.

RPG Benefits Copy Chapter

For Solo Developers Copy Section

• Clear roadmap for implementing complex features
• Prevents architectural mistakes early
• Explicit dependency tracking avoids integration issues
• Enables resuming work after interruptions

For Teams Copy Section

• Parallel development of independent modules
• Clear contracts between modules (explicit dependencies)
• Reduced merge conflicts (proper module boundaries)
• Onboarding aid (architectural overview in PRD)

For AI Agents Copy Section

• Structured context for code generation
• Clear scope boundaries per task
• Dependency awareness prevents incomplete implementations
• Test strategy guidance for TDD workflows

RPG vs Standard Template Copy Chapter

Tips for Best Results Copy Chapter

1. Spend Time on Dependencies Copy Section

The dependency graph section is the most valuable. List all dependencies explicitly, even if they seem obvious.

2. Keep Features Atomic Copy Section

Each feature should be independently testable. If a feature description is vague ("handle data"), break it into specific features.

3. Progressive Refinement Copy Section

Don't try to get everything perfect on the first pass:

1. Fill out high-level sections
2. Review and refine
3. Add detail where needed
4. Let task-master expand break down complex tasks further

4. Use Research Mode Copy Section

task-master parse-prd --research

The --research flag leverages AI to enhance task generation with domain knowledge.

5. Validate Early Copy Section

task-master validate-dependencies

Check for circular dependencies or orphaned modules before starting implementation.

Common Pitfalls Copy Chapter

❌ Mixing Functional and Structural Copy Section

Bad: "Capability: validation.js"
Good: "Capability: Data Validation" → maps to "src/validation/"

❌ Vague Module Boundaries Copy Section

Bad: "Module: utils"
Good: "Module: string-utilities" with clear exports

❌ Implicit Dependencies Copy Section

Bad: "Module: API handlers (needs validation)"
Good: "Module: API handlers, Depends on: [validation, error-handling]"

❌ Skipping Test Strategy Copy Section

Without test strategy, the AI won't know what to test during implementation.

Example Workflow Copy Chapter

1. Discuss idea with AI: Explain your project concept
2. Reference RPG template: Show AI the example_prd_rpg.md
3. Co-create PRD: Work through each section with AI guidance
4. Save to docs: Place in .taskmaster/docs/your-project.md (use .md for better editor support)
5. Parse PRD: task-master parse-prd .taskmaster/docs/your-project.md --research
6. Analyze: task-master analyze-complexity --research
7. Expand: task-master expand --all --research
8. Start work: task-master next

Further Reading Copy Chapter

• PRD Creation and Parsing Guide
• Task Structure Documentation
• Microsoft Research RPG Paper (Original methodology)

2. Official Technical Reference & Guides (eyaltoledano/docs) Copy Chapter

Task Master Documentation

Welcome to the Task Master documentation. Use the links below to navigate to the information you need:

Getting Started Copy Chapter

• Configuration Guide - Set up environment variables and customize Task Master
• Tutorial - Step-by-step guide to getting started with Task Master

Reference Copy Chapter

• Command Reference - Complete list of all available commands
• Task Structure - Understanding the task format and features

Examples & Licensing Copy Chapter

• Example Interactions - Common Cursor AI interaction examples
• Licensing Information - Detailed information about the license

Need More Help? Copy Chapter

If you can't find what you're looking for in these docs, please check the main README or visit our GitHub repository.