> ## Documentation Index
> Fetch the complete documentation index at: https://taskgraph-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install the taskgraph-ai npm package, run taskgraph init in your project, and add the Claude Code plugin for /taskgraph: slash commands.

The [Quick Start](https://taskgraph-ai.com/getting-started/quick-start.md) gets you building in five steps. This page has the detail on each part of the setup: the CLI, the project, the plugin, the optional MCP server and updates. You need [Claude Code](https://docs.claude.com/en/docs/claude-code) installed and signed in (run `claude` once) and Node.js 22.19 or later.

## 1. Install the CLI

```bash theme={null}
npm install -g taskgraph-ai
```

This gives you the `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:

```bash theme={null}
taskgraph init
```

This creates `.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`):

```txt theme={null}
/plugin marketplace add stephennmiller/taskgraph-ai
/plugin install taskgraph@taskgraph
/plugin install taskgraph-hooks@taskgraph
```

The plugin does not register an MCP server. The `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`](https://taskgraph-ai.com/capabilities/cli-viewing-commands#prime-a-coding-agent): 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`](https://taskgraph-ai.com/capabilities/cli-viewing-commands#prime-a-coding-agent), 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:

```bash theme={null}
taskgraph doctor
```

It prints one line per check (Node, Claude Code and its sign-in, the project, the plugin and the MCP server) and the fix under each one that failed, and exits 1 if any did.

## 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:

```bash theme={null}
claude mcp add taskgraph-ai --scope user \
  --env TASKGRAPH_TOOLS=standard \
  -- npx -y taskgraph-ai
```

Restart Claude Code and run `/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:

```json theme={null}
{
  "mcpServers": {
    "taskgraph-ai": {
      "command": "npx",
      "args": ["-y", "taskgraph-ai@<version>"],
      "env": { "TASKGRAPH_TOOLS": "standard" }
    }
  }
}
```

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

Running `taskgraph` 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:

```bash theme={null}
taskgraph upgrade
```

`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/`):

```json theme={null}
{ "autoUpdate": "install" }
```

TaskGraph never installs an update when input isn't a terminal, when `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.

## Upgrading from Task Master or before 0.47

See the [upgrade guide](https://taskgraph-ai.com/upgrading.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.