{"id":26760680,"url":"https://github.com/eyaltoledano/claude-task-master","last_synced_at":"2025-09-09T21:25:42.028Z","repository":{"id":280680607,"uuid":"942837343","full_name":"eyaltoledano/claude-task-master","owner":"eyaltoledano","description":"An AI-powered task-management system you can drop into Cursor, Lovable, Windsurf, Roo, and others.","archived":false,"fork":false,"pushed_at":"2025-05-08T23:34:04.000Z","size":3613,"stargazers_count":8367,"open_issues_count":108,"forks_count":863,"subscribers_count":75,"default_branch":"main","last_synced_at":"2025-05-11T03:43:48.439Z","etag":null,"topics":["ai","cursor","cursor-ai","cursorai","lovable","lovable-dev","roocode","task-manager","tasks","tasks-list","windsurf","windsurf-ai"],"latest_commit_sha":null,"homepage":"https://task-master.dev","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/eyaltoledano.png","metadata":{"files":{"readme":"README-task-master.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-04T18:54:54.000Z","updated_at":"2025-05-11T03:19:54.000Z","dependencies_parsed_at":null,"dependency_job_id":"301dbd8a-d689-43b8-b0c5-0b198790f86b","html_url":"https://github.com/eyaltoledano/claude-task-master","commit_stats":null,"previous_names":["eyaltoledano/claude-task-master"],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eyaltoledano%2Fclaude-task-master","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eyaltoledano%2Fclaude-task-master/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eyaltoledano%2Fclaude-task-master/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/eyaltoledano%2Fclaude-task-master/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/eyaltoledano","download_url":"https://codeload.github.com/eyaltoledano/claude-task-master/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253514553,"owners_count":21920334,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","cursor","cursor-ai","cursorai","lovable","lovable-dev","roocode","task-manager","tasks","tasks-list","windsurf","windsurf-ai"],"created_at":"2025-03-28T18:01:08.896Z","updated_at":"2025-09-09T21:25:42.018Z","avatar_url":"https://github.com/eyaltoledano.png","language":"JavaScript","readme":"# Task Master\n\n### by [@eyaltoledano](https://x.com/eyaltoledano)\n\nA task management system for AI-driven development with Claude, designed to work seamlessly with Cursor AI.\n\n## Requirements\n\n- Node.js 14.0.0 or higher\n- Anthropic API key (Claude API)\n- Anthropic SDK version 0.39.0 or higher\n- OpenAI SDK (for Perplexity API integration, optional)\n\n## Configuration\n\nTaskmaster uses two primary configuration methods:\n\n1.  **`.taskmasterconfig` File (Project Root)**\n\n    - Stores most settings: AI model selections (main, research, fallback), parameters (max tokens, temperature), logging level, default priority/subtasks, project name.\n    - **Created and managed using `task-master models --setup` CLI command or the `models` MCP tool.**\n    - Do not edit manually unless you know what you are doing.\n\n2.  **Environment Variables (`.env` file or MCP `env` block)**\n    - Used **only** for sensitive **API Keys** (e.g., `ANTHROPIC_API_KEY`, `PERPLEXITY_API_KEY`, etc.) and specific endpoints (like `OLLAMA_BASE_URL`).\n    - **For CLI:** Place keys in a `.env` file in your project root.\n    - **For MCP/Cursor:** Place keys in the `env` section of your `.cursor/mcp.json` (or other MCP config according to the AI IDE or client you use) file under the `taskmaster-ai` server definition.\n\n**Important:** Settings like model choices, max tokens, temperature, and log level are **no longer configured via environment variables.** Use the `task-master models` command or tool.\n\nSee the [Configuration Guide](docs/configuration.md) for full details.\n\n## Installation\n\n```bash\n# Install globally\nnpm install -g task-master-ai\n\n# OR install locally within your project\nnpm install task-master-ai\n```\n\n### Initialize a new project\n\n```bash\n# If installed globally\ntask-master init\n\n# If installed locally\nnpx task-master init\n```\n\nThis will prompt you for project details and set up a new project with the necessary files and structure.\n\n### Important Notes\n\n1. **ES Modules Configuration:**\n\n   - This project uses ES Modules (ESM) instead of CommonJS.\n   - This is set via `\"type\": \"module\"` in your package.json.\n   - Use `import/export` syntax instead of `require()`.\n   - Files should use `.js` or `.mjs` extensions.\n   - To use a CommonJS module, either:\n     - Rename it with `.cjs` extension\n     - Use `await import()` for dynamic imports\n   - If you need CommonJS throughout your project, remove `\"type\": \"module\"` from package.json, but Task Master scripts expect ESM.\n\n2. The Anthropic SDK version should be 0.39.0 or higher.\n\n## Quick Start with Global Commands\n\nAfter installing the package globally, you can use these CLI commands from any directory:\n\n```bash\n# Initialize a new project\ntask-master init\n\n# Parse a PRD and generate tasks\ntask-master parse-prd your-prd.txt\n\n# List all tasks\ntask-master list\n\n# Show the next task to work on\ntask-master next\n\n# Generate task files\ntask-master generate\n```\n\n## Troubleshooting\n\n### If `task-master init` doesn't respond:\n\nTry running it with Node directly:\n\n```bash\nnode node_modules/claude-task-master/scripts/init.js\n```\n\nOr clone the repository and run:\n\n```bash\ngit clone https://github.com/eyaltoledano/claude-task-master.git\ncd claude-task-master\nnode scripts/init.js\n```\n\n## Task Structure\n\nTasks in tasks.json have the following structure:\n\n- `id`: Unique identifier for the task (Example: `1`)\n- `title`: Brief, descriptive title of the task (Example: `\"Initialize Repo\"`)\n- `description`: Concise description of what the task involves (Example: `\"Create a new repository, set up initial structure.\"`)\n- `status`: Current state of the task (Example: `\"pending\"`, `\"done\"`, `\"deferred\"`)\n- `dependencies`: IDs of tasks that must be completed before this task (Example: `[1, 2]`)\n  - Dependencies are displayed with status indicators (✅ for completed, ⏱️ for pending)\n  - This helps quickly identify which prerequisite tasks are blocking work\n- `priority`: Importance level of the task (Example: `\"high\"`, `\"medium\"`, `\"low\"`)\n- `details`: In-depth implementation instructions (Example: `\"Use GitHub client ID/secret, handle callback, set session token.\"`)\n- `testStrategy`: Verification approach (Example: `\"Deploy and call endpoint to confirm 'Hello World' response.\"`)\n- `subtasks`: List of smaller, more specific tasks that make up the main task (Example: `[{\"id\": 1, \"title\": \"Configure OAuth\", ...}]`)\n\n## Integrating with Cursor AI\n\nClaude Task Master is designed to work seamlessly with [Cursor AI](https://www.cursor.so/), providing a structured workflow for AI-driven development.\n\n### Setup with Cursor\n\n1. After initializing your project, open it in Cursor\n2. The `.cursor/rules/dev_workflow.mdc` file is automatically loaded by Cursor, providing the AI with knowledge about the task management system\n3. Place your PRD document in the `scripts/` directory (e.g., `scripts/prd.txt`)\n4. Open Cursor's AI chat and switch to Agent mode\n\n### Setting up MCP in Cursor\n\nTo enable enhanced task management capabilities directly within Cursor using the Model Control Protocol (MCP):\n\n1. Go to Cursor settings\n2. Navigate to the MCP section\n3. Click on \"Add New MCP Server\"\n4. Configure with the following details:\n   - Name: \"Task Master\"\n   - Type: \"Command\"\n   - Command: \"npx -y task-master-ai\"\n5. Save the settings\n\nOnce configured, you can interact with Task Master's task management commands directly through Cursor's interface, providing a more integrated experience.\n\n### Initial Task Generation\n\nIn Cursor's AI chat, instruct the agent to generate tasks from your PRD:\n\n```\nPlease use the task-master parse-prd command to generate tasks from my PRD. The PRD is located at scripts/prd.txt.\n```\n\nThe agent will execute:\n\n```bash\ntask-master parse-prd scripts/prd.txt\n```\n\nThis will:\n\n- Parse your PRD document\n- Generate a structured `tasks.json` file with tasks, dependencies, priorities, and test strategies\n- The agent will understand this process due to the Cursor rules\n\n### Generate Individual Task Files\n\nNext, ask the agent to generate individual task files:\n\n```\nPlease generate individual task files from tasks.json\n```\n\nThe agent will execute:\n\n```bash\ntask-master generate\n```\n\nThis creates individual task files in the `tasks/` directory (e.g., `task_001.txt`, `task_002.txt`), making it easier to reference specific tasks.\n\n## AI-Driven Development Workflow\n\nThe Cursor agent is pre-configured (via the rules file) to follow this workflow:\n\n### 1. Task Discovery and Selection\n\nAsk the agent to list available tasks:\n\n```\nWhat tasks are available to work on next?\n```\n\nThe agent will:\n\n- Run `task-master list` to see all tasks\n- Run `task-master next` to determine the next task to work on\n- Analyze dependencies to determine which tasks are ready to be worked on\n- Prioritize tasks based on priority level and ID order\n- Suggest the next task(s) to implement\n\n### 2. Task Implementation\n\nWhen implementing a task, the agent will:\n\n- Reference the task's details section for implementation specifics\n- Consider dependencies on previous tasks\n- Follow the project's coding standards\n- Create appropriate tests based on the task's testStrategy\n\nYou can ask:\n\n```\nLet's implement task 3. What does it involve?\n```\n\n### 3. Task Verification\n\nBefore marking a task as complete, verify it according to:\n\n- The task's specified testStrategy\n- Any automated tests in the codebase\n- Manual verification if required\n\n### 4. Task Completion\n\nWhen a task is completed, tell the agent:\n\n```\nTask 3 is now complete. Please update its status.\n```\n\nThe agent will execute:\n\n```bash\ntask-master set-status --id=3 --status=done\n```\n\n### 5. Handling Implementation Drift\n\nIf during implementation, you discover that:\n\n- The current approach differs significantly from what was planned\n- Future tasks need to be modified due to current implementation choices\n- New dependencies or requirements have emerged\n\nTell the agent:\n\n```\nWe've changed our approach. We're now using Express instead of Fastify. Please update all future tasks to reflect this change.\n```\n\nThe agent will execute:\n\n```bash\ntask-master update --from=4 --prompt=\"Now we are using Express instead of Fastify.\"\n```\n\nThis will rewrite or re-scope subsequent tasks in tasks.json while preserving completed work.\n\n### 6. Breaking Down Complex Tasks\n\nFor complex tasks that need more granularity:\n\n```\nTask 5 seems complex. Can you break it down into subtasks?\n```\n\nThe agent will execute:\n\n```bash\ntask-master expand --id=5 --num=3\n```\n\nYou can provide additional context:\n\n```\nPlease break down task 5 with a focus on security considerations.\n```\n\nThe agent will execute:\n\n```bash\ntask-master expand --id=5 --prompt=\"Focus on security aspects\"\n```\n\nYou can also expand all pending tasks:\n\n```\nPlease break down all pending tasks into subtasks.\n```\n\nThe agent will execute:\n\n```bash\ntask-master expand --all\n```\n\nFor research-backed subtask generation using Perplexity AI:\n\n```\nPlease break down task 5 using research-backed generation.\n```\n\nThe agent will execute:\n\n```bash\ntask-master expand --id=5 --research\n```\n\n## Command Reference\n\nHere's a comprehensive reference of all available commands:\n\n### Parse PRD\n\n```bash\n# Parse a PRD file and generate tasks\ntask-master parse-prd \u003cprd-file.txt\u003e\n\n# Limit the number of tasks generated (default is 10)\ntask-master parse-prd \u003cprd-file.txt\u003e --num-tasks=5\n\n# Allow task master to determine the number of tasks based on complexity\ntask-master parse-prd \u003cprd-file.txt\u003e --num-tasks=0\n```\n\n### List Tasks\n\n```bash\n# List all tasks\ntask-master list\n\n# List tasks with a specific status\ntask-master list --status=\u003cstatus\u003e\n\n# List tasks with subtasks\ntask-master list --with-subtasks\n\n# List tasks with a specific status and include subtasks\ntask-master list --status=\u003cstatus\u003e --with-subtasks\n```\n\n### Show Next Task\n\n```bash\n# Show the next task to work on based on dependencies and status\ntask-master next\n```\n\n### Show Specific Task\n\n```bash\n# Show details of a specific task\ntask-master show \u003cid\u003e\n# or\ntask-master show --id=\u003cid\u003e\n\n# View a specific subtask (e.g., subtask 2 of task 1)\ntask-master show 1.2\n```\n\n### Update Tasks\n\n```bash\n# Update tasks from a specific ID and provide context\ntask-master update --from=\u003cid\u003e --prompt=\"\u003cprompt\u003e\"\n```\n\n### Generate Task Files\n\n```bash\n# Generate individual task files from tasks.json\ntask-master generate\n```\n\n### Set Task Status\n\n```bash\n# Set status of a single task\ntask-master set-status --id=\u003cid\u003e --status=\u003cstatus\u003e\n\n# Set status for multiple tasks\ntask-master set-status --id=1,2,3 --status=\u003cstatus\u003e\n\n# Set status for subtasks\ntask-master set-status --id=1.1,1.2 --status=\u003cstatus\u003e\n```\n\nWhen marking a task as \"done\", all of its subtasks will automatically be marked as \"done\" as well.\n\n### Expand Tasks\n\n```bash\n# Expand a specific task with subtasks\ntask-master expand --id=\u003cid\u003e --num=\u003cnumber\u003e\n\n# Expand a task with a dynamic number of subtasks (ignoring complexity report)\ntask-master expand --id=\u003cid\u003e --num=0\n\n# Expand with additional context\ntask-master expand --id=\u003cid\u003e --prompt=\"\u003ccontext\u003e\"\n\n# Expand all pending tasks\ntask-master expand --all\n\n# Force regeneration of subtasks for tasks that already have them\ntask-master expand --all --force\n\n# Research-backed subtask generation for a specific task\ntask-master expand --id=\u003cid\u003e --research\n\n# Research-backed generation for all tasks\ntask-master expand --all --research\n```\n\n### Clear Subtasks\n\n```bash\n# Clear subtasks from a specific task\ntask-master clear-subtasks --id=\u003cid\u003e\n\n# Clear subtasks from multiple tasks\ntask-master clear-subtasks --id=1,2,3\n\n# Clear subtasks from all tasks\ntask-master clear-subtasks --all\n```\n\n### Analyze Task Complexity\n\n```bash\n# Analyze complexity of all tasks\ntask-master analyze-complexity\n\n# Save report to a custom location\ntask-master analyze-complexity --output=my-report.json\n\n# Use a specific LLM model\ntask-master analyze-complexity --model=claude-3-opus-20240229\n\n# Set a custom complexity threshold (1-10)\ntask-master analyze-complexity --threshold=6\n\n# Use an alternative tasks file\ntask-master analyze-complexity --file=custom-tasks.json\n\n# Use Perplexity AI for research-backed complexity analysis\ntask-master analyze-complexity --research\n```\n\n### View Complexity Report\n\n```bash\n# Display the task complexity analysis report\ntask-master complexity-report\n\n# View a report at a custom location\ntask-master complexity-report --file=my-report.json\n```\n\n### Managing Task Dependencies\n\n```bash\n# Add a dependency to a task\ntask-master add-dependency --id=\u003cid\u003e --depends-on=\u003cid\u003e\n\n# Remove a dependency from a task\ntask-master remove-dependency --id=\u003cid\u003e --depends-on=\u003cid\u003e\n\n# Validate dependencies without fixing them\ntask-master validate-dependencies\n\n# Find and fix invalid dependencies automatically\ntask-master fix-dependencies\n```\n\n### Add a New Task\n\n```bash\n# Add a new task using AI\ntask-master add-task --prompt=\"Description of the new task\"\n\n# Add a task with dependencies\ntask-master add-task --prompt=\"Description\" --dependencies=1,2,3\n\n# Add a task with priority\ntask-master add-task --prompt=\"Description\" --priority=high\n```\n\n## Feature Details\n\n### Analyzing Task Complexity\n\nThe `analyze-complexity` command:\n\n- Analyzes each task using AI to assess its complexity on a scale of 1-10\n- Recommends optimal number of subtasks based on configured DEFAULT_SUBTASKS\n- Generates tailored prompts for expanding each task\n- Creates a comprehensive JSON report with ready-to-use commands\n- Saves the report to scripts/task-complexity-report.json by default\n\nThe generated report contains:\n\n- Complexity analysis for each task (scored 1-10)\n- Recommended number of subtasks based on complexity\n- AI-generated expansion prompts customized for each task\n- Ready-to-run expansion commands directly within each task analysis\n\n### Viewing Complexity Report\n\nThe `complexity-report` command:\n\n- Displays a formatted, easy-to-read version of the complexity analysis report\n- Shows tasks organized by complexity score (highest to lowest)\n- Provides complexity distribution statistics (low, medium, high)\n- Highlights tasks recommended for expansion based on threshold score\n- Includes ready-to-use expansion commands for each complex task\n- If no report exists, offers to generate one on the spot\n\n### Smart Task Expansion\n\nThe `expand` command automatically checks for and uses the complexity report:\n\nWhen a complexity report exists:\n\n- Tasks are automatically expanded using the recommended subtask count and prompts\n- When expanding all tasks, they're processed in order of complexity (highest first)\n- Research-backed generation is preserved from the complexity analysis\n- You can still override recommendations with explicit command-line options\n\nExample workflow:\n\n```bash\n# Generate the complexity analysis report with research capabilities\ntask-master analyze-complexity --research\n\n# Review the report in a readable format\ntask-master complexity-report\n\n# Expand tasks using the optimized recommendations\ntask-master expand --id=8\n# or expand all tasks\ntask-master expand --all\n```\n\n### Finding the Next Task\n\nThe `next` command:\n\n- Identifies tasks that are pending/in-progress and have all dependencies satisfied\n- Prioritizes tasks by priority level, dependency count, and task ID\n- Displays comprehensive information about the selected task:\n  - Basic task details (ID, title, priority, dependencies)\n  - Implementation details\n  - Subtasks (if they exist)\n- Provides contextual suggested actions:\n  - Command to mark the task as in-progress\n  - Command to mark the task as done\n  - Commands for working with subtasks\n\n### Viewing Specific Task Details\n\nThe `show` command:\n\n- Displays comprehensive details about a specific task or subtask\n- Shows task status, priority, dependencies, and detailed implementation notes\n- For parent tasks, displays all subtasks and their status\n- For subtasks, shows parent task relationship\n- Provides contextual action suggestions based on the task's state\n- Works with both regular tasks and subtasks (using the format taskId.subtaskId)\n\n## Best Practices for AI-Driven Development\n\n1. **Start with a detailed PRD**: The more detailed your PRD, the better the generated tasks will be.\n\n2. **Review generated tasks**: After parsing the PRD, review the tasks to ensure they make sense and have appropriate dependencies.\n\n3. **Analyze task complexity**: Use the complexity analysis feature to identify which tasks should be broken down further.\n\n4. **Follow the dependency chain**: Always respect task dependencies - the Cursor agent will help with this.\n\n5. **Update as you go**: If your implementation diverges from the plan, use the update command to keep future tasks aligned with your current approach.\n\n6. **Break down complex tasks**: Use the expand command to break down complex tasks into manageable subtasks.\n\n7. **Regenerate task files**: After any updates to tasks.json, regenerate the task files to keep them in sync.\n\n8. **Communicate context to the agent**: When asking the Cursor agent to help with a task, provide context about what you're trying to achieve.\n\n9. **Validate dependencies**: Periodically run the validate-dependencies command to check for invalid or circular dependencies.\n\n## Example Cursor AI Interactions\n\n### Starting a new project\n\n```\nI've just initialized a new project with Claude Task Master. I have a PRD at scripts/prd.txt.\nCan you help me parse it and set up the initial tasks?\n```\n\n### Working on tasks\n\n```\nWhat's the next task I should work on? Please consider dependencies and priorities.\n```\n\n### Implementing a specific task\n\n```\nI'd like to implement task 4. Can you help me understand what needs to be done and how to approach it?\n```\n\n### Managing subtasks\n\n```\nI need to regenerate the subtasks for task 3 with a different approach. Can you help me clear and regenerate them?\n```\n\n### Handling changes\n\n```\nWe've decided to use MongoDB instead of PostgreSQL. Can you update all future tasks to reflect this change?\n```\n\n### Completing work\n\n```\nI've finished implementing the authentication system described in task 2. All tests are passing.\nPlease mark it as complete and tell me what I should work on next.\n```\n\n### Analyzing complexity\n\n```\nCan you analyze the complexity of our tasks to help me understand which ones need to be broken down further?\n```\n\n### Viewing complexity report\n\n```\nCan you show me the complexity report in a more readable format?\n```\n","funding_links":[],"categories":["JavaScript","MCP Extensions","Project Management Mcp Servers","A01_文本生成_文本对话","Claude Code","✨ AI Tools for Developers","MCP Servers","MCPs","HarmonyOS","Developer Tools","AI编程任务管理","Repos","Task and Project Management","Framework","AI-Driven Task Management","Project \u0026 Knowledge Management","Tooling 🧰","CLI \u0026 Terminal Tools","Platforms","Development Toolkits","🗂️ Task, Memory \u0026 Workspace Management"],"sub_categories":["Taskmaster","大语言对话模型及数据","Laravel","Software Development","Windows Manager","How to Submit","Other IDEs","Orchestrators","Specialized CLI Tools","Task Management"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feyaltoledano%2Fclaude-task-master","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Feyaltoledano%2Fclaude-task-master","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Feyaltoledano%2Fclaude-task-master/lists"}