Taskmaster CLI

A TypeScript CLI tool for managing project workflows using LLMs. Generate design documents, requirements, and task breakdowns with iterative feedback using a spec-first architecture with .taskmaster folder structure.

What's New in v1.1.0

✨ Spec-First Architecture

• Kubernetes-style contexts: Set active spec once, work within it automatically
• Project organization: Group related D/R/T documents under named specifications
• Context switching: taskmaster specs --use <spec-id> (like kubectl use-context)
• Automatic spec creation: Init process now creates your first spec by default

🎯 Spec Management Commands

taskmaster specs -l                    # List all specs
taskmaster specs --use my-feature      # Set active spec context
taskmaster specs --current             # Show current context
taskmaster specs --unset               # Return to global mode
taskmaster specs -c                    # Create new spec

Installation

Global Installation (Recommended)

npm install -g @akashokik/taskmaster-cli

From Source

git clone <repository-url>
cd taskmaster-cli
npm install
npm run build
npm link  # For local development

Model Selection Made Easy

View all available models:

taskmaster models                    # All providers
taskmaster models --provider openai  # Specific provider
taskmaster models --provider anthropic
taskmaster models --provider ollama

Quick model reference:

taskmaster init --list-models       # Quick overview during setup

Usage

Taskmaster works in any project by creating a .taskmaster folder structure. You can run commands from anywhere within your project directory tree.

Quick Start (Spec-First Workflow)

1. Initialize in your project root:

cd your-project
taskmaster init    # Creates initial spec + sets context automatically

2. All commands now work within the active spec:

# Check current context
taskmaster specs --current

# Create design document (within active spec)
taskmaster design --description "Build a web app for task management"

# Generate requirements (within active spec)  
taskmaster requirements

# Break down into tasks (within active spec)
taskmaster tasks

3. Multiple specs workflow:

# Create additional specs for different features
taskmaster specs -c

# Switch between specs
taskmaster specs --use my-feature
taskmaster design              # Works within my-feature spec

taskmaster specs --use backend-api
taskmaster requirements        # Works within backend-api spec

5. Browse and manage tasks:

taskmaster browse              # Interactive task browser
taskmaster browse --list       # Simple task list
taskmaster browse --task 5     # View specific task details
taskmaster browse --search "auth" # Search tasks

Advanced Usage

Fast feedback without editor:

taskmaster design --feedback --feedback-text "Add more security details"
taskmaster requirements --feedback --feedback-text "Need more acceptance criteria"
taskmaster tasks --feedback --feedback-text "Break down tasks further"

Automatically refine documents with AI enhancement:

taskmaster design --refine
taskmaster requirements --refine
taskmaster tasks --refine

Interactive feedback (improved - no slow external editor):

taskmaster design --feedback      # Simple text input or multi-line
taskmaster requirements --feedback
taskmaster tasks --feedback

Task browsing and management:

# Interactive browser with navigation
taskmaster browse

# Quick task lookup
taskmaster browse --task 3
taskmaster browse --search "database"

# List all tasks
taskmaster browse --list --page-size 20

Agent-Friendly Features

Taskmaster provides optimized commands for automated workflows and agent usage:

Quick Task Operations

Simple task listing:

taskmaster tasks -p                    # Print tasks: num|id|title|assignee|effort
taskmaster tasks -p -q                 # Quiet mode (no headers)
taskmaster browse -l -q                # All tasks with status (pipe-delimited)

Status and progress tracking:

taskmaster browse -c                   # Task counts (human-readable)
taskmaster browse -c -q                # CSV format: total,todo,in-progress,done
taskmaster browse --progress           # Completion percentage
taskmaster browse --progress -q        # Compact: done/total,percentage

Individual task details:

taskmaster browse -t 3                 # View task 3 (formatted)
taskmaster browse -t 3 -q              # Compact: id|title|status|assignee|effort

Efficient Bulk Operations

Update multiple tasks efficiently:

# Update all tasks to same status
taskmaster browse --set-status-all DONE

# Update a range of tasks
taskmaster browse --set-status-range 1-5:DONE

# Update single task (existing feature)
taskmaster browse --set-status 1:IN-PROGRESS

Agent quick reference:

taskmaster examples -q                 # Compact command reference
taskmaster examples                    # Detailed agent guide

Output Formats

• Normal: Human-readable with Unicode formatting and colors
• Quiet (-q): Pipe-delimited format for easy parsing
• Status workflow: TODO → IN-PROGRESS → DONE

Example agent workflow:

# Check current progress
taskmaster browse --progress -q        # Returns: 2/5,40%

# List incomplete tasks
taskmaster browse -s TODO -q           # Returns: task1|TODO|Setup auth|...

# Bulk update completed tasks
taskmaster browse --set-status-range 1-3:DONE

# Verify completion
taskmaster browse -c -q                # Returns: 5,0,0,5

Work from any subdirectory:

# Works from anywhere in your project
cd src/components
taskmaster design --refine

Features

• Multiple LLM provider support (OpenAI, Anthropic, Ollama)
• Document versioning - keeps history of changes
• Interactive feedback loops - iteratively improve documents
• Global installation - works in any project
• Smart directory detection - finds .taskmaster folder automatically
• Clean structure - markdown files directly in .taskmaster/
• Fast input options - no slow external editors required
• Graceful exit handling - clean cancellation with Ctrl+C
• Comprehensive model selection - guided setup with model details
• Interactive task browser - scroll, search, and view tasks by index
• Agent-friendly indexing - numbered task access for automation

Project Structure

After running taskmaster init, your project will have:

your-project/
├── .taskmaster/
│   ├── .taskmaster-config.json  # LLM configuration
│   ├── .current-spec            # Active spec context
│   ├── specs.json              # Specs metadata
│   ├── specs/                  # Spec-organized documents
│   │   ├── main-project/       # Your initial spec
│   │   │   ├── design.md       # Design document
│   │   │   ├── requirements.md # Requirements document
│   │   │   └── tasks.md        # Task breakdown
│   │   └── my-feature/         # Additional specs
│   │       ├── design.md
│   │       └── requirements.md
│   └── versions/               # Global document history
│       ├── design-2024-01-15T10-30-00.md
│       └── requirements-2024-01-15T10-35-00.md
├── src/                        # Your project files
└── ...                         # Other project files

Configuration

On first run (taskmaster init), you'll configure:

• LLM Provider: OpenAI, Anthropic, or Ollama
• API Key: For OpenAI/Anthropic (optional for Ollama)
• Model: Specific model to use
• Base URL: For self-hosted Ollama instances

Configuration is stored in .taskmaster/.taskmaster-config.json and can be updated by running taskmaster init again.

Requirements

• Node.js 16.0.0 or higher
• LLM API access (OpenAI, Anthropic) or local Ollama installation

License

ISC