Taskmaster and Claude Code: How Task Files Drive an Agent

Taskmaster is an open-source task manager for AI-driven development, published on npm as task-master-ai. You give it a product requirements document; it uses a model to break the document into tasks with priorities, dependencies and test strategies, and writes them to .taskmaster/tasks/tasks.json in your project. Claude Code then works from that file, either through Taskmaster’s MCP server or by running its command-line tool, asking “what is next?”, implementing it and marking it done. The file is the plan and the agent follows it. What it does not try to be is a place where people outside the repository see, assign and review the work, which is where a shared board comes in.

What Taskmaster is

Taskmaster is made by Eyal Toledano and Ralph Khreish. The code is in the claude-task-master repository, and its documentation is published on the website of Hamster, tryhamster.com. The licence↗ (opens in a new tab) is MIT with the Commons Clause added: you can use, change and share it freely, but the clause withholds the right to sell it, meaning to offer a product or service whose value comes substantially from Taskmaster itself. For using it on your own projects that makes no difference; for building a paid service on it, read the licence.

It is editor-neutral. The README↗ (opens in a new tab) gives set-up for Cursor, Windsurf, VS Code, Amazon Q and Claude Code, and it can write rule files for each so the assistant knows how to use it. Taskmaster calls models itself for the heavy steps — parsing a document, expanding a task, research — with three roles you configure: a main model, a research model and a fallback. Those need an API key for the provider you choose, or one of the options that needs none, such as using Claude Code itself as the provider.

From a PRD to tasks.json

The documented flow starts with a written requirements document. The README’s advice is blunt — “Always start with a detailed PRD” — because the tasks are only as good as the document they come from.

task-master init
task-master parse-prd .taskmaster/docs/prd.txt
task-master analyze-complexity --research
task-master expand --id=4
task-master next
task-master set-status --id=4 --status=done

• init sets up the .taskmaster/ directory: configuration in config.json, documents in docs/, tasks in tasks/tasks.json.
• parse-prd reads the document and writes its task list. Each task has an id, title, description, status, dependencies, priority, implementation details, a test strategy and optional subtasks.
• Statuses↗ (opens in a new tab) are pending, in-progress, done, review, deferred and cancelled.
• analyze-complexity scores each task and suggests how many subtasks it needs; expand generates them.
• next returns a task whose dependencies are all done, which is how an agent picks what to do without a person choosing each time.
• Tags keep separate task lists in one file — per branch, environment or project phase — so parallel lines of work do not collide.

Because tasks.json lives in the repository, it moves with branches like any other file. The tutorial↗ (opens in a new tab) notes that teammates creating tasks on different branches can produce merge conflicts in it, and documents the move command for resolving them.

How Claude Code uses it

There are two routes, and both end with Claude reading and updating the same file.

• MCP. The README’s one-line set-up is claude mcp add taskmaster-ai -- npx -y task-master-ai. Claude then calls tools such as get_tasks, next_task, get_task, set_task_status, parse_prd and expand_task, and you talk to it in plain sentences: “what is the next task?”, “implement task 3”.
• The command line. Claude runs task-master next, task-master show 3 and task-master set-status through its shell, like any other tool in the project.

The MCP server loads 36 tools by default, which the README puts at about 21,000 tokens of context. The TASK_MASTER_TOOLS variable cuts that down: core loads seven tools, standard fifteen, or you can list the ones you want.

claude mcp add task-master-ai --scope user \
  --env TASK_MASTER_TOOLS="core" \
  -- npx -y task-master-ai@latest

Taskmaster also documents a loop command↗ (opens in a new tab), tm loop, that drives Claude Code for you. Each iteration finds the next task that respects dependencies and priorities, builds a prompt from it, launches Claude Code to implement it, and moves on; it stops when every task is done or one is blocked, and records progress in .taskmaster/loop-progress.txt so it can resume. It is a close cousin of the technique in Claude Code tasks vs the Ralph loop, with a task file deciding what each pass works on.

One practical point: Claude Code has its own task list as well, the checklist it keeps with TaskCreate and TaskUpdate. With Taskmaster installed there are two lists called “tasks” in one session. Say in CLAUDE.md that Taskmaster’s file is the plan and Claude’s own list is for the steps inside one Taskmaster task. Claude Code tasks vs to-dos explains the built-in one.

File-based tracking and board-based tracking

Taskmaster keeps its tasks locally in the project in what its documentation↗ (opens in a new tab) calls solo mode. It also has a team mode that connects to Hamster’s hosted service for shared briefs and real-time sync. The comparison below is with the local file, which is how most people meet it.

• Where it lives — Taskmaster: a JSON file in the repository, versioned with the code. Board: a hosted service, outside the repository.
• Who reads it — Taskmaster: anyone with the repository, through an editor, the CLI or an assistant. Board: its members, in a browser, on a phone or through an assistant, without opening the code.
• Structure — Taskmaster: dependencies, subtasks, complexity scores and a test strategy per task, generated from a document. fenbs: a kind (feature, enhancement or bug), a priority from 1 to 10, a project and one of four fixed lanes — To Do, Next Up, In Progress, Completed. Related tasks are linked both ways, but a link does not block anything.
• Who may change it — Taskmaster: whoever can write to the file. fenbs: each member holds a role, each assistant connection carries scopes (read, write, comment), and one connection can be revoked on its own.
• Record of change — Taskmaster: git history of the file. fenbs: a history of every change with who made it, an assistant’s changes shown as “Claude via” the person it acts for.

Neither is a weaker version of the other. A task file is at its best when an agent is decomposing and executing a specification it can read end to end. A board is at its best when the people deciding what gets built, and checking what came out, are not in the repository all day.

When to combine them

The split that works is by level. The board holds outcomes; Taskmaster holds the implementation plan for one outcome.

1. A feature is a task on the board. People write the Problem, set its priority and move it to Next Up when it is ready.
2. When Claude Code picks it up, it creates a Taskmaster tag named after the board task’s ref with add-tag and switches to it with use-tag, writes the PRD from that board task, runs parse-prd, and comments on the board task with how many Taskmaster tasks it produced.
3. Claude works through next inside Taskmaster. The board hears about milestones, not every subtask.
4. When the tag’s tasks are all done, Claude comments on the board task with the commits and the checks, and moves it on. A person reviews it there.

## Taskmaster and the board
- The board says WHAT and in what order. Taskmaster says HOW.
- Take work only from Next Up on the fenbs board.
- Plan it in Taskmaster under its own tag: add-tag fe-051, then use-tag fe-051.
- Do not copy Taskmaster subtasks onto the board. Comment milestones only.
- Found something out of scope? File it on the board in To Do, not in Taskmaster.

The last line matters most. Anything Claude discovers along the way that nobody asked for belongs where people decide priorities, not buried in an agent’s plan. For the filing side of that, see an issue tracker for AI agents; for pulling ready work from a board, a kanban board for Claude Code.