# Taskmaster: features, protocols, quickstart

## TL;DR

Taskmaster (npm package task-master-ai) is a task-management CLI and MCP server by Eyal Toledano and Ralph Khreish that turns a PRD into dependency-ordered tasks for AI coding agents and can hand them to Claude Code. It is source-available under MIT with Commons Clause; team sync runs on Hamster's hosted platform. It suits PRD-driven projects.

## Key facts

| Field | Value |
| --- | --- |
| Type | Orchestrator |
| Languages / SDKs | JavaScript, TypeScript |
| License | unknown |
| Pricing model | [Open core](https://tryhamster.com/pricing) |
| Orchestration pattern | Other |
| GitHub stars | 28,113 (as of 2026-09-30) |
| GitHub forks | 2,616 |
| Last push | 2026-04-28 |
| Latest release | task-master-ai@0.43.1 |
| Repository | [eyaltoledano/claude-task-master](https://github.com/eyaltoledano/claude-task-master) |
| Website | [tryhamster.com](https://tryhamster.com) |
| Documentation | [tryhamster.com](https://tryhamster.com/docs/taskmaster) |
| Last verified | 2026-09-30 |

## Key features

- `task-master parse-prd` turns a requirements document into a task list with dependencies; tasks can be expanded into subtasks and scored for complexity. ([source](https://github.com/eyaltoledano/claude-task-master/blob/main/README.md))
- An MCP server (`npx -y task-master-ai`) exposes task tools to editors, with `TASK_MASTER_TOOLS` choosing a core, standard, full or custom tool set to limit context use. ([source](https://tryhamster.com/docs/taskmaster/capabilities/mcp))
- Separate main, research and fallback models can be set across many providers, including Claude Code and Codex CLI subscriptions and local models through Ollama or LM Studio. ([source](https://tryhamster.com/docs/taskmaster/ai-providers/overview))
- `start` launches Claude Code with one task's full context; `loop` repeats this task by task, respecting dependencies, until everything is done or a task is blocked. ([source](https://tryhamster.com/docs/taskmaster/automation/loop))
- `clusters` groups tasks that can run in parallel from the dependency graph; `clusters start` launches Claude Code with agent teams enabled to work through them, with dry-run and resume options. ([source](https://tryhamster.com/docs/taskmaster/capabilities/clusters))
- `rules add` writes rules files, MCP config and slash commands for about a dozen editors and agents, including Cursor, Claude Code, Windsurf, Codex, Gemini CLI and OpenCode. ([source](https://tryhamster.com/docs/taskmaster/ide-setup/supported-editors))
- Team mode stores tasks on Hamster's cloud with real-time sync and briefs, and Hamster runs the AI calls instead of each member's API keys. ([source](https://tryhamster.com/docs/taskmaster/team/overview))

## Architecture and orchestration pattern

Pattern: Other.

Taskmaster is a Node.js CLI plus an MCP server that share one task store. In solo mode, tasks live in local JSON files under `.taskmaster/`, organised into tags (separate task lists per feature or branch), each task carrying status, dependencies, subtasks and optional metadata. The AI-backed commands (parse PRD, expand, update, research) call whichever main, research or fallback model is configured.

It does not run its own agents. An editor agent calls the MCP tools (for example `next_task`, `set_task_status`), or Taskmaster launches Claude Code: `start` for a single task, `loop` for one task after another in dependency order, and `clusters start` for parallel work. For clusters it computes groups of tasks with no mutual dependencies from the dependency graph and starts a Claude Code session with the experimental agent-teams setting enabled, leaving the sub-agent spawning to Claude Code.

Progress for automated runs is written to disk (`.taskmaster/loop-progress.txt`, cluster checkpoints), so an interrupted run can resume. In team mode the same commands work against briefs stored on Hamster's servers instead of local files.

### Human in the loop

Most work is driven by a person: you write the PRD, review the generated tasks, and ask for the next task, an expansion or a status change through the CLI or chat. `start` opens an interactive Claude Code session for one task. For automation, `loop --verbose` streams Claude's work, Ctrl+C interrupts a loop or cluster run and progress is saved for resuming, and `clusters start` displays the execution plan for review before launching (or only prints it with `--dry-run`). The Codex CLI provider exposes Codex's approval and sandbox modes. Taskmaster has no approval gate of its own between automated tasks beyond these.

### Harnesses it can drive

- Claude Code ([evidence](https://tryhamster.com/docs/taskmaster/automation/loop))
- Codex ([evidence](https://github.com/eyaltoledano/claude-task-master/blob/main/docs/providers/codex-cli.md))
- OpenCode ([evidence](https://tryhamster.com/docs/taskmaster/ide-setup/supported-editors))

## Protocols

| Protocol | Support | Evidence | Note |
| --- | --- | --- | --- |
| MCP | Yes (checked 2026-09-30) | [link](https://tryhamster.com/docs/taskmaster/capabilities/mcp) | Server: the mcp-server package (built on fastmcp) registers up to 36 task tools, selectable with TASK_MASTER_TOOLS; the README shows adding it to Claude Code, Cursor, Windsurf and VS Code. |
| A2A | Unknown (checked 2026-09-30) | — | No mention of A2A in the README, the Taskmaster docs pages read (MCP, loop, clusters, editors, providers, team, FAQ) or the repository file tree. |
| AG-UI | Unknown (checked 2026-09-30) | — | No mention of AG-UI in the README, docs pages read or repository file tree; not listed in the AG-UI README. |

## Best for

- Breaking a PRD into ordered, dependency-aware tasks that a coding agent in Cursor, Claude Code or another MCP client can work through. ([shortlist](https://multiagentguide.top/best/coding-agents.md))
- Running Claude Code unattended over a task list with `loop`, or in parallel groups with `clusters start`. ([shortlist](https://multiagentguide.top/best/coding-agents.md))
- Keeping task planning offline with local models (Ollama, LM Studio) and local JSON task files. ([shortlist](https://multiagentguide.top/best/self-hosted-local.md))
- Solo developers who want task state kept as plain JSON files in the repository rather than in a hosted tracker.

## Not for

- Companies that want to resell Taskmaster or offer it as a hosted service; the Commons Clause forbids that.
- Users who need an actively released tool: the last release was March 2026 and the main branch has been quiet since April 2026.
- Automated execution with agents other than Claude Code; `start`, `loop` and `clusters` launch Claude Code.

## Quickstart

```sh
npm install -g task-master-ai
```

Install not yet verified by this site.

```bash
npm install -g task-master-ai
cd my-app && task-master init          # creates .taskmaster/

# Use Claude Code as the model (no API key), or put a provider key in .env
task-master models --set-main claude-code/sonnet

# Write .taskmaster/docs/prd.txt, then generate and inspect tasks
task-master parse-prd .taskmaster/docs/prd.txt
task-master list
task-master next

# Hand tasks to Claude Code
task-master start 3              # one task, interactive
task-master loop --verbose       # task after task until done or blocked

# Or register the MCP server in Claude Code instead
claude mcp add taskmaster-ai -- npx -y task-master-ai
```

### Common pitfalls

- Requires Node.js 20 or newer.
- AI commands need at least one provider key in `.env` or the MCP `env` block, unless you use Claude Code, Codex CLI, Gemini CLI or a local model. If an editor shows `0 tools enabled`, restart it and check the keys.
- The docs use `tm`, which is a shell alias that `task-master init` adds; the installed binary is `task-master`.
- The README says all 36 MCP tools (about 21,000 tokens) load by default, while the MCP docs page says the core set is the default; set `TASK_MASTER_TOOLS` explicitly.
- `clusters start` enables Claude Code's experimental agent teams and recommends iTerm2 with `tmux -CC`.
- The Codex CLI provider needs Codex CLI 0.42+ and a ChatGPT subscription for OAuth.
- If `task-master init` hangs, the README suggests running `scripts/init.js` with Node directly.

Official quickstart: https://github.com/eyaltoledano/claude-task-master/blob/main/README.md

## Pros

- Turns a PRD into a dependency graph of tasks and subtasks that agents can query one step at a time. ([source](https://github.com/eyaltoledano/claude-task-master/blob/main/README.md))
- Configurable MCP tool sets let you trade features for context size (7, 15 or 36 tools, or a custom list). ([source](https://tryhamster.com/docs/taskmaster/capabilities/mcp))
- Can run without a paid API key through Claude Code, Gemini CLI or local models, and with Codex through a ChatGPT subscription. ([source](https://tryhamster.com/docs/taskmaster/ai-providers/overview))
- Automated runs save progress and checkpoints, so interrupted loop or cluster runs can resume. ([source](https://tryhamster.com/docs/taskmaster/capabilities/clusters))
- Sets up rules and MCP config for many editors with one `rules add` command. ([source](https://tryhamster.com/docs/taskmaster/ide-setup/supported-editors))

## Cons

- Source-available rather than open source: the Commons Clause forbids selling Taskmaster or offering it as a hosted service. ([source](https://github.com/eyaltoledano/claude-task-master/blob/main/LICENSE))
- Releases stopped at 0.43.1 (31 March 2026); the last main-branch commits in April 2026 moved the docs to tryhamster.com after the task-master.dev domain was retired. ([source](https://github.com/eyaltoledano/claude-task-master/pull/1691))
- Open bug reports from June 2026 describe MCP path checks that allow writes outside the session root, with no maintainer reply. ([source](https://github.com/eyaltoledano/claude-task-master/issues/1714))
- The README and the MCP docs disagree on which tool set loads by default, which affects context usage. ([source](https://github.com/eyaltoledano/claude-task-master/blob/main/README.md))
- Parallel execution depends on Claude Code's experimental agent-teams feature and a tmux-capable terminal. ([source](https://tryhamster.com/docs/taskmaster/capabilities/clusters))

## Alternatives

- [BMad Method](https://multiagentguide.top/tools/bmad-method.md)
- [Vibe Kanban](https://multiagentguide.top/tools/vibe-kanban.md)
- [HumanLayer](https://multiagentguide.top/tools/humanlayer.md)
- [Ruflo](https://multiagentguide.top/tools/ruflo.md)
- [wshobson/agents](https://multiagentguide.top/tools/wshobson-agents.md)

## FAQ

### Does Taskmaster support MCP?

Yes. It ships an MCP server (`npx -y task-master-ai`) with up to 36 task tools; `TASK_MASTER_TOOLS` limits which ones load.

### Is Taskmaster free?

Solo use is free under MIT with Commons Clause, which is source-available and forbids reselling or hosting it. Team mode runs on Hamster, which has a free plan and paid Team and Enterprise plans.

### Why does the repository homepage point to tryhamster.com?

In April 2026 the README's documentation links moved to tryhamster.com/docs/taskmaster, a merged PR states the task-master.dev domain is retired, and the README now has a 'More from Hamster' section and a hiring banner for Hamster. The README does not describe the business relationship further.

### Which coding agents does it work with?

Automation commands launch Claude Code. Codex CLI can serve as the model provider. Rules, MCP config or slash commands are generated for Cursor, Claude Code, Windsurf, VS Code, Roo, Cline, Codex, Gemini CLI, Kiro, Zed, Amp, Trae and OpenCode.

### What language is Taskmaster written in?

JavaScript and TypeScript on Node.js 20+, distributed on npm as task-master-ai.

## Sources

- [claude-task-master GitHub repository](https://github.com/eyaltoledano/claude-task-master)
- [Taskmaster README](https://github.com/eyaltoledano/claude-task-master/blob/main/README.md)
- [Task Master LICENSE (MIT with Commons Clause)](https://github.com/eyaltoledano/claude-task-master/blob/main/LICENSE)
- [Taskmaster documentation](https://tryhamster.com/docs/taskmaster)
- [Hamster homepage](https://tryhamster.com)
- [Hamster pricing](https://tryhamster.com/pricing)
- [Taskmaster MCP tools](https://tryhamster.com/docs/taskmaster/capabilities/mcp)
- [Taskmaster AI providers](https://tryhamster.com/docs/taskmaster/ai-providers/overview)
- [Loop command](https://tryhamster.com/docs/taskmaster/automation/loop)
- [Clusters and execution](https://tryhamster.com/docs/taskmaster/capabilities/clusters)
- [Supported editors](https://tryhamster.com/docs/taskmaster/ide-setup/supported-editors)
- [Team collaboration](https://tryhamster.com/docs/taskmaster/team/overview)
- [Codex CLI provider](https://github.com/eyaltoledano/claude-task-master/blob/main/docs/providers/codex-cli.md)
- [PR #1691: replace retired task-master.dev URLs](https://github.com/eyaltoledano/claude-task-master/pull/1691)
- [Issue #1714: projectRoot bypass allows writes outside the MCP session root](https://github.com/eyaltoledano/claude-task-master/issues/1714)

## Unknown fields

license: GitHub reports NOASSERTION; the LICENSE file is the MIT License plus the Commons Clause License Condition v1.0 (licensors Eyal Toledano and Ralph Khreish), which removes the right to sell the software, including as a hosted or support service, so it is source-available rather than OSI open source. pricing_model is recorded as open-core with that caveat: solo use is free, and team mode is a hosted Hamster product with paid plans. protocols.a2a and protocols.agui: no mentions in the README, the docs pages listed in sources or the repository file tree; not in the AG-UI README. Harness note: the supported-editors table shows no MCP config for OpenCode, but the OpenCode profile in src/profiles/opencode.js writes the Taskmaster MCP server into opencode.json.

Corrections or removal requests: support@multiagentguide.top

---

Data as of 2026-09-30. Not affiliated with listed projects. HTML version: https://multiagentguide.top/tools/claude-task-master