claude once) and Node.js 22.19 or later.
1. Install the CLI
taskgraph command and taskgraph-mcp, the optional MCP server. To skip the install, run any command through npx, for example npx -y -p taskgraph-ai taskgraph list.
2. Initialize your project
From your project folder:.taskgraph/ (tasks, docs, config), and a CLAUDE.md import with TaskGraph’s workflow guide. Pass --no-claude to skip the CLAUDE.md import. init does not install slash commands (step 3 does) and doesn’t register the MCP server unless you pass --mcp (step 4).
Running init again is safe: it says the project is already set up and adds only what is missing.
3. Install the plugin
The Claude Code plugin is the only way to get slash commands. It adds the/taskgraph: slash commands and two agents (task-executor, task-checker):
task-checker agent uses the taskgraph show CLI, and uses the MCP tool instead if you registered the server as taskgraph-ai (step 4).
The plugin also adds a taskgraph skill, and taskgraph-hooks adds four hooks. In a project with a .taskgraph/ folder, each Claude Code session (and each resume after compaction) starts with the output of taskgraph prime: the task in progress, what’s ready next, and the workflow rules. Elsewhere the hook does nothing. The plugin states the oldest CLI it works with; when yours is older, or not installed, the hook tells Claude to ask you to run npm install -g taskgraph-ai@latest instead.
After compaction the hook also asks Claude to log a note on the task in progress, from the conversation summary, so what it did before compaction isn’t lost. While a task is in progress, each prompt you send carries that task and its unchecked acceptance criteria (taskgraph prime --current, at most 13 lines), so Claude keeps it in view in a long session; with nothing in progress the hook adds nothing and doesn’t start the CLI.
When Claude ticks off the last item of its own todo list (the list Claude Code shows while it works, kept with the TaskCreate and TaskUpdate tools or, with CLAUDE_CODE_ENABLE_TASKS=0, with TodoWrite), a hook logs the list as one note on the task in progress, so the steps it took stay with the task. A list with an item still open logs nothing, the same list isn’t logged twice in a row, and the items don’t become subtasks. Since the task tools send one item at a time, the hook keeps the session’s list in todos-<session ID> in the private folder described below. Models that Claude Code gives no todo list tools keep no list, so there’s nothing to log.
When Claude finishes a turn and a task is still in progress with no note from this session, the Stop hook reminds Claude once per session to log what it did with taskgraph note, or to close the task. Otherwise, when the task in progress has unchecked acceptance criteria, the Stop hook keeps Claude going once and names them: Claude checks off the ones that hold, finishes the work, or says why it’s stopping (waiting on you, say). It does this once per session for each set of unchecked criteria, so later turns, such as answering a question, end normally until a criterion is checked or the task changes. It never keeps Claude going twice in a row. The session starts when the session hook runs: it saves that time in a private folder in your temp folder ($TMPDIR/taskgraph-<your user ID>/session-<session ID>, readable only by you), and compacting the conversation keeps it. The Stop hook keeps the criteria it last named beside it, in unmet-<session ID>, and without that folder it doesn’t hold Claude back. The taskgraph skill tells Claude to use TaskGraph when you ask what to do next or plan work in a project that has .taskgraph/.
Check that each step worked:
4. (Optional) Add the MCP server
The slash commands (from the plugin) and the CLI do everything without MCP. Add the server only if you want to drive TaskGraph in plain language:/mcp. taskgraph-ai should show as connected. If you see 0 tools enabled, restart Claude Code and confirm npx -y taskgraph-ai starts on its own in a terminal.
The equivalent .mcp.json entry is:
<version> with the one taskgraph --version prints. A pinned version means everyone who opens the project runs the same server, not whatever npm tags latest that day. taskgraph init --mcp writes a pinned entry for you, and running it again after an upgrade moves the pin.
Staying up to date
Runningtaskgraph in a terminal checks npm for a newer version, at most once an hour, and tells you on stderr when one is out, so redirected or piped output never holds the notice. When npm can’t be reached within 3 seconds, the next check waits 10 minutes. The check does not install the update. Install it yourself:
taskgraph upgrade always asks npm, whatever an earlier check cached, and exits non-zero when npm can’t be reached.
To install updates automatically, set TASKGRAPH_AUTO_UPDATE=install, or put this in ~/.taskgraph/auto-update.json (your home directory, not a project’s .taskgraph/):
CI is set, when the command prints JSON, or from loop and loop --parallel. Those runs set TASKGRAPH_SKIP_AUTO_UPDATE=1 on every process they start. Set that yourself to skip the version check. If an install is already running, another one skips it instead of installing twice.

