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

$3

- 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 (like kubectl use-context)
- Automatic spec creation: Init process now creates your first spec by default

$3

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

$3

`bash
npm install -g @akashokik/taskmaster-cli
`

$3

`bash
git clone
cd taskmaster-cli
npm install
npm run build
npm link # For local development
`

Model Selection Made Easy

View all available models:
`bash
taskmaster models # All providers
taskmaster models --provider openai # Specific provider
taskmaster models --provider anthropic
taskmaster models --provider ollama
`

Quick model reference:
`bash
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.

$3

1. Initialize in your project root:
`bash
cd your-project
taskmaster init # Creates initial spec + sets context automatically
`

2. All commands now work within the active spec:
`bash


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:
`bash


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:
`bash
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
`

$3

Fast feedback without editor:
`bash
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:
`bash
taskmaster design --refine
taskmaster requirements --refine
taskmaster tasks --refine
`

Interactive feedback (improved - no slow external editor):
`bash
taskmaster design --feedback # Simple text input or multi-line
taskmaster requirements --feedback
taskmaster tasks --feedback
`

Task browsing and management:
`bash


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:

$3

Simple task listing:
`bash
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:
`bash
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:
`bash
taskmaster browse -t 3 # View task 3 (formatted)
taskmaster browse -t 3 -q # Compact: id|title|status|assignee|effort
`

$3

Update multiple tasks efficiently:
`bash


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:
`bash
taskmaster examples -q # Compact command reference
taskmaster examples # Detailed agent guide
`

$3

- 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:
`bash


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:
`bash


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