JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 46
  • Score
    100M100P100Q83982F
  • License MIT

A task management system for ambitious AI-driven development that doesn't overwhelm and confuse Cursor.

Package Exports

  • booplex-task-manager
  • booplex-task-manager/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (booplex-task-manager) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Booplex Task Manager

Looking for detailed usage or workflow guides?

See docs/usage.md for a full command reference and docs/how-to-guide.md for practical step-by-step examples and best practices.

by @eyaltoledano, upgraded by gabelu

A universal AI-driven task management system using the Google Gemini model, designed for seamless collaboration with Cursor AI.

Project Background

AI Task Master is an enhanced and improved version of the original claude-task-manager project. After analyzing the original project's design and capabilities, the following shortcomings were identified:

  1. Model Limitations: The Claude model API used in the project is expensive (input $3/million tokens, output $15/million tokens), and Claude's risk control is extremely strict, making the API easily blocked in China.
  2. Lack of Knowledge Integration: Task splitting relies entirely on the PRD document, lacking deep understanding of business knowledge.
  3. Single Language: Output is limited to English, requiring secondary translation for Chinese users.
  4. Cumbersome Operation: Task management mainly relies on CLI commands, lacking an intuitive visual presentation.
  5. Inflexible Splitting: The number of tasks and subtasks must be specified, lacking intelligence and flexibility.

Based on these issues, we made comprehensive improvements to the system:

  1. Model Upgrade: All Claude calls replaced with Gemini 2.5 Pro, which is free and more stable.
  2. Knowledge Base Integration: Supports passing a business knowledge base path during task splitting, allowing AI to reference business context for more accurate task breakdowns.
  3. Bilingual Support: With the USE_SPANISH environment variable, generates both English instructions and Spanish descriptions, ensuring execution quality and improved readability.
  4. Visual Management: Added web server functionality, providing an intuitive Spanish interface for task management, with one-click copy for English instructions.
  5. Intelligent Splitting: Optimized task splitting logic to automatically determine the appropriate granularity based on task complexity.

These improvements make Task Master a more powerful and user-friendly AI task management tool, especially suitable for Spanish developers.

Development Status

Sprint 2: Medium Priority MCP Tools - COMPLETED

Sprint 2 has been successfully completed with all planned MCP tools implemented and tested:

  • ✅ parsePRD Tool: Parse PRD documents and generate task structures
  • ✅ Subtask Management Tools:
    • removeSubtask: Remove subtasks from tasks
    • clearSubtasks: Clear all subtasks from specified tasks
    • expandAll: Expand multiple tasks with subtasks in one operation
  • ✅ Dependency Management Tools:
    • addDependency: Add dependency relationships between tasks
    • removeDependency: Remove dependency relationships
  • ✅ complexityReport Tool: Generate and view task complexity analysis reports

All tests are passing, and the tools are fully integrated into the MCP server.

System Screenshot

Task Master Web UI

The Task Master Web interface displays the task list and details, supporting bilingual display and status management.

Core Advantages

  • Free and Stable AI Model: Uses Gemini 2.5 Pro, no high API costs
  • Business Knowledge Integration: Task splitting can incorporate business background for improved understanding
  • Bilingual Support: Generates both English instructions and Spanish descriptions for better usability and execution
  • Visual Interface: Web UI for task management, freeing you from cumbersome CLI operations
  • Flexible Task Splitting: Intelligently determines the best granularity for task breakdown
  • Shell Alias Support: Option to add btm shell alias for quicker CLI access
  • Cursor MCP Integration: Automatic configuration of Cursor AI tooling for seamless workflow

Shell Alias Support

During project initialization with task-manager init, you'll be prompted to add a shell alias:

Add shell alias for task-manager? This lets you type "btm" instead of "task-manager" (Y/n):

Benefits of using the shell alias:

  • Faster Workflow: Type btm instead of task-manager for all commands
  • Convenience: Reduces typing for frequently used commands
  • Examples:
    # Instead of:
task-manager list

# You can use:
btm list

# Works with all commands:
btm next
btm expand --id=3
btm server

The alias is added to your shell configuration file (.bashrc or .zshrc) and becomes available in new terminal sessions or after running source ~/.bashrc (or equivalent for your shell).

Note: Shell aliases are not supported on Windows platforms.

Cursor AI Integration

Booplex Task Manager automatically configures Cursor or RooCode AI integration during project initialization. This setup:

  • Creates .cursor/mcp.json configuration for AI-assisted development
  • Configures the MCP server with your environment variables
  • Enables advanced AI workflows with Cursor editor

Benefits of Cursor integration:

  • AI-Assisted Task Management: Ask Cursor to expand tasks, check dependencies, or suggest next steps
  • Contextual AI Assistance: Cursor understands your task structure and project context
  • Seamless Workflow: No additional setup needed - works out of the box
  • Custom Environment: Uses your project's environment variables and configuration

The MCP configuration includes all environment variables from your .env file, including:

  • API keys (configured for Gemini and Perplexity)
  • Model settings
  • Project configuration
  • Debugging options
  • Language preferences

To use the integration, simply open your project in the Cursor editor and start chatting with the AI about your tasks.

System Requirements

  • Node.js 14.0.0 or higher
  • Google API key (for Gemini API access)
  • OpenAI SDK (optional, for Perplexity API integration)

Configuration

Configure via environment variables in the .env file at the project root:

Required Configuration

  • GOOGLE_API_KEY: Google API key for Gemini access (required)

Optional Configuration

  • MAX_TOKENS: Maximum tokens for model responses (default: 8192)
  • TEMPERATURE: Model response temperature (default: 0.7)
  • GEMINI_BASE_URL: Custom API endpoint for Google Gemini (optional)
  • PERPLEXITY_API_KEY: Perplexity API key for research-backed subtask generation
  • PERPLEXITY_MODEL: Specify the Perplexity model to use (default: "sonar-pro")
  • DEBUG: Enable debug logging (default: false)
  • LOG_LEVEL: Log level - debug, info, warn, error (default: info)
  • DEFAULT_SUBTASKS: Default number of subtasks when expanding (default: 3)
  • DEFAULT_PRIORITY: Default priority for generated tasks (default: medium)
  • PROJECT_NAME: Override the default project name in tasks.json
  • PROJECT_VERSION: Override the default version in tasks.json
  • USE_SPANISH: If set, generates Spanish translation fields for tasks (e.g., titleTrans, descriptionTrans)
  • GEMINI_BASE_URL: Supports configuring a proxy for GEMINI access

AI Model Selection Logic

Task Master uses different AI models for various operations, particularly leveraging Perplexity AI's research capabilities when requested. The selection logic prioritizes specific models for certain tasks:

  1. PERPLEXITY_MODEL (Default: sonar-pro):

    • Used exclusively when the --research flag (CLI) or research: true parameter (MCP) is specified for commands/tools like analyze-complexity, expand, update, update-task, and add-task.
    • Leverages Perplexity's web search capabilities for research-backed generation.
    • Requires PERPLEXITY_API_KEY to be set.
    • If research is requested but Perplexity fails (e.g., missing key), it falls back to Gemini using the logic below.

  2. COMPLEXITY_MODEL (Default: Uses MODEL if not set):

    • Used specifically for the analyze-complexity command/tool when the --research flag/parameter is not used.
    • Allows dedicating a potentially different Gemini/compatible model optimized for analytical tasks and JSON output.
    • If not set, it defaults to the MODEL variable.

  3. MODEL (Default: gemini-1.5-pro-latest via config):

    • The general-purpose model used for most AI operations when --research is not specified and COMPLEXITY_MODEL is not set or not applicable (e.g., for parse-prd, expand, update, add-task without research).
    • This is the primary fallback model.

Priority Order (Example: analyze-complexity):

  • With --research: PERPLEXITY_MODEL -> (Fallback on error) -> COMPLEXITY_MODEL -> MODEL -> Default Config Model
  • Without --research: COMPLEXITY_MODEL -> MODEL -> Default Config Model

Note: You can sometimes override the model selection for a specific operation using the --model command-line option or the model parameter in MCP tool calls, though this depends on the specific command/tool implementation.

Installation

# Global installation
npm install -g ai-task-manager

# Or local installation in your project
npm install ai-task-manager

Initialize a New Project

# If installed globally
task-manager init

# If installed locally
npx task-manager-init

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

Important Notes

  1. This package uses ES modules. Your package.json should include "type": "module".
  2. You need a valid Google API key with appropriate permissions to use Gemini Pro 2.5.

Quick Start with Global Commands

After installing the package globally, you can use these CLI commands from any directory:

# Initialize a new project
task-manager init

# Parse PRD and generate tasks
task-manager parse-prd your-prd.txt

# Parse PRD and generate tasks with business knowledge base
task-manager parse-prd your-prd.txt -k docs/

# List all tasks
task-manager list

# Show the next task to work on
task-manager next

# Generate task files
task-manager generate

# Start the web UI for task management
task-manager server

Task Structure

Tasks in tasks.json have the following structure:

  • id: Unique identifier for the task (e.g., 1)
  • title: Brief, descriptive title for the task (e.g., "Initialize Repo")
  • titleTrans: Spanish translation of the task title (e.g., "Inicializar repositorio") (generated when USE_SPANISH is set)
  • description: Concise summary of the task (e.g., "Create a new repository, set up initial structure.")
  • descriptionTrans: Spanish translation of the task description (e.g., "Crear un nuevo repositorio, configurar la estructura inicial.") (generated when USE_SPANISH is set)
  • status: Current status of the task (e.g., "pending", "done", "deferred")
  • dependencies: IDs of tasks that must be completed before this one (e.g., [1, 2])
    • Dependencies are shown with status indicators (✅ for completed, ⏱️ for pending)
    • This helps quickly identify which prerequisite tasks are blocking work
  • priority: Importance level of the task (e.g., "high", "medium", "low")
  • details: In-depth implementation notes (e.g., "Use GitHub client ID/secret, handle callback, set session token.")
  • detailsTrans: Spanish translation of implementation details (generated when USE_SPANISH is set)
  • testStrategy: Verification approach (e.g., "Deploy and call endpoint to confirm 'Hello World' response.")
  • testStrategyTrans: Spanish translation of the test strategy (generated when USE_SPANISH is set)
  • subtasks: List of smaller, more specific tasks that make up the main task (e.g., [{"id": 1, "title": "Configure OAuth", ...}])

Business Knowledge Integration

Task Master now supports incorporating a business knowledge base during task generation:

# Parse PRD with a knowledge base directory
task-manager parse-prd your-prd.txt -k docs/

# Parse PRD with a specific knowledge file
task-manager parse-prd your-prd.txt -k docs/domain_knowledge.md

# Use the knowledge base when generating subtasks (if already used during parse-prd, no need to specify again)
task-manager expand --id=3 -k docs/

Benefits of business knowledge integration:

  • Task splitting is more aligned with actual business needs
  • Improves the accuracy and relevance of task descriptions
  • Reduces errors caused by AI's lack of business understanding
  • Once the knowledge base is introduced during PRD parsing, it will be automatically used for subsequent subtask splitting

Bilingual Support

When the USE_SPANISH=true environment variable is set, the system generates both English instructions and Spanish descriptions:

  • English fields are for AI execution, ensuring instruction quality
  • Spanish fields are for human review, improving comprehension
  • The web interface displays Spanish fields by default (if present)

Spanish fields include:

  • titleTrans: Spanish translation of the task title
  • descriptionTrans: Spanish translation of the task description
  • detailsTrans: Spanish translation of implementation details
  • testStrategyTrans: Spanish translation of the test strategy

Web Interface

Task Master includes a built-in web interface for task visualization and management.

Start the Web Server

# Start the web server on the default port (3002)
task-manager server

# Use a custom port
task-manager server --port=4000

# Specify an alternative tasks.json file
task-manager server --file=custom-tasks.json

# Start and show debug path information
task-manager server --debug-paths

Web Interface Features

  • Task List View: Browse all tasks, filter by status
  • Task Detail View: View comprehensive information for each task
  • Subtask Management: View and interact with subtasks
  • Status Updates: Change task status directly from the web interface
  • Localization Support: Switch between English and Spanish content via the locale parameter
  • API Access: Access task data programmatically via RESTful endpoints

API Endpoints

The web server provides the following RESTful API endpoints:

  • GET /api/tasks: Get all tasks and their subtasks

    # Get tasks in the default language (Spanish)
curl http://localhost:3002/api/tasks

# Get tasks in English
curl http://localhost:3002/api/tasks?locale=en

  • GET /api/tasks/:taskId: Get a specific task by ID

    # Get task with ID 1 in English
curl http://localhost:3002/api/tasks/1?locale=en

  • PUT /api/tasks/:taskId: Update task properties

    # Update task status
curl -X PUT http://localhost:3002/api/tasks/1 -H "Content-Type: application/json" -d '{"status":"done"}'

  • PUT /api/tasks/:taskId/subtasks/:subtaskId: Update subtask properties

    # Update subtask status
curl -X PUT http://localhost:3002/api/tasks/1/subtasks/2 -H "Content-Type: application/json" -d '{"status":"done"}'

AI-Driven Development Workflow

With Cursor agent pre-configuration (via rules file), you can follow this workflow:

1. Task Discovery and Selection

Ask the agent about available tasks:

What tasks are available to work on?

The agent will:

  • Run task-manager list to view all tasks
  • Run task-manager next to determine the next task to work on
  • Analyze dependencies to see which tasks are ready
  • Prioritize tasks by priority and ID order
  • Suggest the next task to implement

2. Task Implementation

When implementing a task, the agent will:

  • Refer to the task's details section for implementation guidance
  • Consider dependencies on previous tasks
  • Follow project coding standards
  • Create appropriate tests based on the task's testStrategy

You can ask:

Let's implement task 3. What does it involve?

3. Task Verification

Before marking a task as complete, verify according to:

  • The testStrategy specified for the task
  • Any automated tests in the codebase
  • Manual verification if necessary

4. Task Completion

When a task is complete, tell the agent:

Task 3 is now complete. Please update its status.

The agent will execute:

task-manager set-status --id=3 --status=done

5. Handling Implementation Drift

If during implementation you find:

  • The current approach differs significantly from the plan
  • Future tasks need modification due to current implementation choices
  • New dependencies or requirements have emerged

tell the agent:

We changed the approach. We are now using Express instead of Fastify. Please update all future tasks to reflect this change.

The agent will execute:

task-manager update --from=4 --prompt="Now we are using Express instead of Fastify."

This will rewrite or adjust subsequent tasks in tasks.json while preserving completed work.

6. Breaking Down Complex Tasks

For complex tasks that need finer granularity:

Task 5 looks complex. Can you break it down into subtasks?

The agent will execute:

task-manager expand --id=5 --num=3

You can provide additional context:

Please break down task 5, focusing on security considerations.

The agent will execute:

task-manager expand --id=5 --prompt="Focus on security aspects"

You can also expand all pending tasks:

Please break down all pending tasks into subtasks.

The agent will execute:

task-manager expand --all

For research-backed subtask generation using Perplexity AI:

Please use research-backed generation to break down task 5.

The agent will execute:

task-manager expand --id=5 --research

Command Reference

Below is a comprehensive reference for all available commands:

Parse PRD

# Parse PRD file and generate tasks
task-manager parse-prd <prd-file.txt>

# Limit the number of generated tasks
task-manager parse-prd <prd-file.txt> --num-tasks=10

# Parse PRD with a business knowledge base
task-manager parse-prd <prd-file.txt> -k docs/

# Parse PRD with a specific knowledge file
task-manager parse-prd <prd-file.txt> -k docs/domain_knowledge.md

List Tasks

# List all tasks
task-manager list

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

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

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

Show Next Task

# Show the next task to work on based on dependencies and status
task-manager next

Show Specific Task

# Show details for a specific task
task-manager show <id>
# or
task-manager show --id=<id>

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

Update Tasks

# Update tasks from a specific ID with context
task-manager update --from=<id> --prompt="<prompt>"

Generate Task Files

# Generate individual task files from tasks.json
task-manager generate

Set Task Status

# Set the status of a single task
task-manager set-status --id=<id> --status=<status>

# Set the status of multiple tasks
task-manager set-status --id=1,2,3 --status=<status>

# Set the status of subtasks
task-manager set-status --id=1.1,1.2 --status=<status>

When a task is marked as "done", all its subtasks will also be marked as "done" automatically.

Expand Tasks

# Expand a specific task with subtasks
task-manager expand --id=<id> --num=<number>

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

# Expand all pending tasks
task-manager expand --all

# Force regenerate subtasks for tasks that already have them
task-manager expand --all --force

# Research-backed subtask generation for a specific task
task-manager expand --id=<id> --research

# Research-backed generation for all tasks
task-manager expand --all --research

Clear Subtasks

# Clear subtasks for a specific task
task-manager clear-subtasks --id=<id>

# Clear subtasks for multiple tasks
task-manager clear-subtasks --id=1,2,3

# Clear subtasks for all tasks
task-manager clear-subtasks --all

Analyze Task Complexity

# Analyze complexity for all tasks
task-manager analyze-complexity

# Save the report to a custom location
task-manager analyze-complexity --output=my-report.json

# Use a specific LLM model
task-manager analyze-complexity --model=claude-3-opus-20240229

# Set a custom complexity threshold (1-10)
task-manager analyze-complexity --threshold=6

# Use an alternative tasks file
task-manager analyze-complexity --file=custom-tasks.json

# Research-backed complexity analysis using Perplexity AI
task-manager analyze-complexity --research

View Complexity Report

# Show the task complexity analysis report
task-manager complexity-report

# View the report at a custom location
task-manager complexity-report --file=my-report.json

Manage Task Dependencies

# Add a dependency to a task
task-manager add-dependency --id=<id> --depends-on=<id>

# Remove a dependency from a task
task-manager remove-dependency --id=<id> --depends-on=<id>

# Validate dependencies without fixing them
task-manager validate-dependencies

# Automatically find and fix invalid dependencies
task-manager fix-dependencies

Add New Task

# Add a new task with AI assistance
task-manager add-task --prompt="<task description>"

# Add a task with dependencies and priority
task-manager add-task --prompt="<task description>" --dependencies=1,2 --priority=high

Server Commands

# Start the web server for task visualization and management
task-manager server

# Use a custom port (default is 3002)
task-manager server --port=4000

# Specify an alternative tasks.json file
task-manager server --file=custom-tasks.json

# Debug server path resolution issues
task-manager server --debug-paths

Changelog

Latest Enhancements

  • Model Upgrade: Switched from Claude to Gemini 2.5 Pro for free, stable API access
  • Knowledge Base Integration: Incorporate business knowledge background during task splitting
  • Bilingual Support: Generate both English instructions and Spanish descriptions for tasks
  • Web Management Interface: Added task-manager server command to launch the visual task management system
  • Route Optimization: Fixed route priorities to ensure correct API endpoint handling
  • API Error Handling: Added dedicated 404 responses for API endpoints
  • Static File Resolution: Enhanced path detection for reliable static asset serving
  • Execution Permission Handling: CLI runner automatically sets appropriate execution permissions
  • Path Debugging: Debug mode helps troubleshoot deployment issues

Migration Note

If you are upgrading from a previous version with Spanish support:

  • All translation and localization features now use Spanish instead of Chinese.
  • Environment variable is now USE_SPANISH (not USE_CHINESE).
  • Task fields and web UI will show Spanish translations when enabled.
  • The system is ready for further language expansion if needed.