JSPM

⚠️ BETA WARNING: This is warp-task-master, a BETA custom fork of task-master-ai with experimental Warp AI integration. Use at your own risk!

🔗 Want the original stable version? → task-master-ai by @eyaltoledano

Warp Task Master (BETA): Experimental custom task management system with Warp AI integration and human-readable profile names.

| Docs

🌟 Warp AI Enhancements (BETA)

⚠️ EXPERIMENTAL: These features are in beta testing. For production use, consider the original stable task-master-ai.

This experimental fork adds Warp terminal integration features:

✨ Human-Readable Profile Names

• 👍 Problem Solved: No more cryptic profile IDs like 4SM7QEB6PSpcMwUHEcl6V3 in your config files
• 📝 Team-Friendly: Share config files with readable names like "Sonnet 4.5" instead of random IDs
• 🔄 Dynamic Resolution: Your system automatically converts names to your local Warp profile IDs
• 🚀 Seamless: Works with existing Warp subscriptions and profiles

🛠️ Enhanced Profile Management

# List all your Warp profiles with readable names
warp-task-master warp-profiles

# Set models using human-readable names
warp-task-master models --set-main "Sonnet 4.5" --warp
warp-task-master models --set-main "GPT 5 + Sonet 4.5" --warp

# Your config now stores readable names!
cat .taskmaster/config.json | jq '.models.main.modelId'
# Output: "Sonnet 4.5" (instead of "4SM7QEB6PSpcMwUHEcl6V3")

🌍 Perfect for Teams

• Before: Team members couldn't share configs (profile IDs are user-specific)
• After: Share configs safely using human-readable profile names
• Smart: Each user's system resolves names to their own local profile IDs

Original Credits

Based on excellent work by @eyaltoledano & @RalphEcom

Fork maintained by @TheLazyIndianTechie

A task management system for AI-driven development with Claude, designed to work seamlessly with Cursor AI and enhanced with Warp terminal integration.

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)

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.

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)
• Warp AI (no API key required - requires Warp subscription & CLI)

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

📦 Installation (BETA - Warp Enhanced Fork)

🚨 BETA SOFTWARE WARNING: This is experimental software with potential bugs and instability.

🔒 For production use: Install the stable original task-master-ai instead.

🧪 Proceed only if: You want to test experimental Warp AI features and understand the risks.

Option A: Install from GitHub (BETA - Use at Your Own Risk)

# ⚠️  BETA SOFTWARE - Install globally from GitHub
npm install -g https://github.com/TheLazyIndianTechie/warp-task-master.git

# Or clone and install locally for development/testing
git clone https://github.com/TheLazyIndianTechie/warp-task-master.git
cd warp-task-master
npm install
npm run build
npm link  # Makes 'warp-task-master' available globally

⚠️ Reminder: This uses a separate warp-task-master command to avoid conflicts with the original task-master-ai.

Option B: Use with MCP (Enhanced)

For MCP usage, update your editor config to point to this fork:

{
  "mcpServers": {
    "warp-task-master": {
      "command": "npx",
      "args": ["-y", "https://github.com/TheLazyIndianTechie/warp-task-master.git"],
      "env": {
        "ANTHROPIC_API_KEY": "YOUR_ANTHROPIC_API_KEY_HERE",
        "OPENAI_API_KEY": "YOUR_OPENAI_KEY_HERE"
        // ... other API keys
      }
    }
  }
}

✅ Verify Installation

Note: Warp-specific commands require the Warp CLI to be installed first. See Warp AI Support section below.

# Check version (should show 1.0.0-beta.2)
warp-task-master --version

# Test Warp integration (BETA feature)
warp-task-master warp-profiles

# Set a model with human-readable name (BETA feature)
warp-task-master models --set-main "Sonnet 4.5" --warp

📝 Note: If you see issues, consider using the stable task-master-ai instead.

💡 Command Name: This fork uses warp-task-master to avoid conflicts with the original task-master command.

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

Manual Configuration

Cursor & Windsurf (mcpServers)

{
  "mcpServers": {
    "warp-task-master": {
      "command": "npx",
      "args": ["-y", "warp-task-master"],
      "env": {
        "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": {
    "warp-task-master": {
      "command": "npx",
      "args": ["-y", "warp-task-master"],
      "env": {
        "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 warp-task-master 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 warp-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 (Warp Fork)

Installation

# Install Warp fork globally  
npm install -g https://github.com/TheLazyIndianTechie/warp-task-master.git

# OR install locally within your project
npm install https://github.com/TheLazyIndianTechie/warp-task-master.git

Initialize a new project

# If installed globally
warp-task-master init

# If installed locally
npx warp-task-master init

# Initialize project with specific rules
warp-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
warp-task-master init

# Parse a PRD and generate tasks
warp-task-master parse-prd your-prd.txt

# List all tasks
warp-task-master list

# Show the next task to work on
warp-task-master next

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

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

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

# Generate task files
warp-task-master generate

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

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

Warp AI Support

Task Master supports Warp AI agents through the Warp CLI, providing subscription-based access without requiring API keys:

• Models: All Warp agent profiles (Default, YOLO Code, Sonnet 4.5, GPT 5 + Sonnet 4.5)
• Requirements: Active Warp subscription and warp-preview CLI installed
• Benefits: No API keys needed, uses your Warp subscription
• Team-friendly: Human-readable profile names in configs ("Sonnet 4.5" vs cryptic IDs)

Installation

1. Install Warp CLI

# Via Homebrew (Recommended)
brew tap warpdotdev/warp
brew install --cask warp-cli

# Verify installation
which warp-preview
warp-preview agent profile list

2. Login to Warp

warp-preview login

3. Configure Task Master to use Warp

# List available Warp profiles
warp-task-master warp-profiles

# Set main model to Warp (use human-readable names)
warp-task-master models --set-main "Sonnet 4.5" --warp

# Or use profile IDs directly (automatically converted to names)
warp-task-master models --set-main "4SM7QEB6PSpcMwUHEcl6V3" --warp

# Set research model
warp-task-master models --set-research "YOLO Code" --warp

# Set fallback model
warp-task-master models --set-fallback "Default" --warp

Available Warp Profiles

Note: Profile availability may vary based on your Warp subscription tier. Run warp-task-master warp-profiles to see your current profiles.

Usage Examples

# Create tasks using Warp AI
warp-task-master add-task --prompt "Implement user authentication"

# Parse PRD with Warp AI
warp-task-master parse-prd your-prd.txt

# Research with Warp AI
warp-task-master research "Latest React patterns for 2024"

Team Configuration

Warp profiles use human-readable names in config files, making them safe to commit:

{
  "models": {
    "main": {
      "provider": "warp",
      "modelId": "Sonnet 4.5",  // ← Human-readable name, not cryptic ID
      "maxTokens": 100000
    }
  }
}

Each team member's system automatically resolves "Sonnet 4.5" to their local Warp profile ID, enabling seamless team collaboration.

Profile Management

# List all available profiles
warp-task-master warp-profiles

# Refresh profile cache
warp-task-master warp-profiles --refresh

# Check current model configuration
warp-task-master models

Troubleshooting

CLI Not Found: Install Warp CLI via Homebrew or from Warp app settings

Authentication Failed: Run warp-preview login and ensure you have an active subscription

Profile Not Found: Use warp-task-master warp-profiles to see available profiles

Troubleshooting

If warp-task-master init doesn't respond

Try running it with Node directly:

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

Or clone the repository and run:

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

Contributors

Star History

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.