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

# Tutorial

> Set up TaskGraph and use it for AI-driven development in Claude Code

This tutorial will guide you through setting up and using TaskGraph for AI-driven development.

## Initial Setup

You need [Claude Code](https://docs.claude.com/en/docs/claude-code) installed and signed in (run `claude` once) and Node.js 22.13 or later. TaskGraph needs no API keys.

1. **Install the package**

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

2. **Initialize your project** from its folder:

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

This creates `.taskgraph/` and imports TaskGraph's workflow guide from your project's `CLAUDE.md`. Add `--mcp` to also write a `.mcp.json` entry for the MCP server.

3. **(Optional) Use the MCP server.** Slash commands and the CLI do everything without it. To drive TaskGraph in plain language, register the server and run `/mcp` in Claude Code to check that it is connected:

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

4. **Place your PRD** in `.taskgraph/docs/` (for example `.taskgraph/docs/prd.md`).

5. **Talk to Claude Code** (or use the `/taskgraph:` slash commands from the [plugin](https://taskgraph-ai.com/getting-started/quick-start/installation.md) or the CLI):

```
Can you parse my PRD at .taskgraph/docs/prd.md?
What's the next task I should work on?
Can you help me implement task 3?
```

## Common Commands

After setting up TaskGraph, you can use these commands via slash commands, AI prompts or the CLI:

```bash theme={null}
# Parse a PRD and generate tasks
taskgraph parse-prd .taskgraph/docs/prd.md

# List all tasks
taskgraph list

# Show the next task to work on
taskgraph next
```

## Initial Task Generation

In Claude Code, instruct the agent to generate tasks from your PRD:

```
Please use the taskgraph parse-prd command to generate tasks from my PRD. The PRD is located at .taskgraph/docs/prd.md.
```

The agent will execute:

```bash theme={null}
taskgraph parse-prd .taskgraph/docs/prd.md
```

This will:

* Parse your PRD document
* Generate a structured `tasks.json` file with tasks, dependencies, priorities, and test strategies
* The agent will understand this process due to the imported `CLAUDE.md` guide

### Generate Individual Task Files

Next, ask the agent to generate individual task files:

```
Please generate individual task files from tasks.json
```

## AI-Driven Development Workflow

Claude Code is pre-configured (via the imported `CLAUDE.md` guide) to follow this workflow:

### 1. Task Discovery and Selection

Ask the agent to list available tasks:

```
What tasks are available to work on next?
```

```
Can you show me tasks 1, 3, and 5 to understand their current status?
```

The agent will:

* Run `taskgraph list` to see all tasks
* Run `taskgraph next` to determine the next task to work on
* Run `taskgraph show 1,3,5` to display multiple tasks with interactive options
* Analyze dependencies to determine which tasks are ready to be worked on
* Prioritize tasks by priority, then by how much work they unblock, then fewer dependencies, then ID order
* Suggest the next task(s) to implement

### 2. Task Implementation

When implementing a task, the agent will:

* Reference the task's details section for implementation specifics
* Consider dependencies on previous tasks
* Follow the project's coding standards
* Create appropriate tests based on the task's testStrategy

You can ask:

```
Let's implement task 3. What does it involve?
```

### 2.1. Viewing Multiple Tasks

For efficient context gathering and batch operations:

```
Show me tasks 5, 7, and 9 so I can plan my implementation approach.
```

The agent will:

* Run `taskgraph show 5,7,9` to display a compact summary table
* Show task status, priority, and progress indicators
* Provide an interactive action menu with batch operations
* Allow you to perform group actions like marking multiple tasks as in-progress

### 3. Task Verification

Before marking a task as complete, verify it according to:

* The task's specified testStrategy
* Any automated tests in the codebase
* Manual verification if required

### 4. Task Completion

When a task is completed, tell the agent:

```
Task 3 is now complete. Please update its status.
```

The agent will execute:

```bash theme={null}
taskgraph set-status --id=3 --status=done
```

### 5. Handling Implementation Drift

If during implementation, you discover that:

* The current approach differs significantly from what was planned
* Future tasks need to be modified due to current implementation choices
* New dependencies or requirements have emerged

Tell the agent:

```
We've decided to use MongoDB instead of PostgreSQL. Can you update all future tasks (from ID 4) to reflect this change?
```

The agent will execute:

```bash theme={null}
taskgraph update --from=4 --prompt="Now we are using MongoDB instead of PostgreSQL."

# OR, if research is needed to find best practices for MongoDB:
taskgraph update --from=4 --prompt="Update to use MongoDB, researching best practices" --research
```

This will rewrite or re-scope subsequent tasks in tasks.json while preserving completed work.

### 6. Reorganizing Tasks

If you need to reorganize your task structure:

```
I think subtask 5.2 would fit better as part of task 7 instead. Can you move it there?
```

The agent will execute:

```bash theme={null}
taskgraph move --from=5.2 --to=7.3
```

You can reorganize tasks in various ways:

* Moving a standalone task to become a subtask: `--from=5 --to=7`
* Moving a subtask to become a standalone task: `--from=5.2 --to=7`
* Moving a subtask to a different parent: `--from=5.2 --to=7.3`
* Reordering subtasks within the same parent: `--from=5.2 --to=5.4`
* Moving a task to a new ID position: `--from=5 --to=25` (even if task 25 doesn't exist yet)
* Moving multiple tasks at once: `--from=10,11,12 --to=16,17,18` (must have same number of IDs, TaskGraph will look through each position)

When moving tasks to new IDs:

* The system automatically creates placeholder tasks for non-existent destination IDs
* This prevents accidental data loss during reorganization
* Any tasks that depend on moved tasks will have their dependencies updated
* When moving a parent task, all its subtasks are automatically moved with it and renumbered

This is particularly useful as your project understanding evolves and you need to refine your task structure.

### 7. Resolving Merge Conflicts with Tasks

When working with a team, you might encounter merge conflicts in your tasks.json file if multiple team members create tasks on different branches. The move command makes resolving these conflicts straightforward:

```
I just merged the main branch and there's a conflict with tasks.json. My teammates created tasks 10-15 while I created tasks 10-12 on my branch. Can you help me resolve this?
```

The agent will help you:

1. Keep your teammates' tasks (10-15)
2. Move your tasks to new positions to avoid conflicts:

```bash theme={null}
# Move your tasks to new positions (e.g., 16-18)
taskgraph move --from=10 --to=16
taskgraph move --from=11 --to=17
taskgraph move --from=12 --to=18
```

This approach preserves everyone's work while maintaining a clean task structure, making it much easier to handle task conflicts than trying to manually merge JSON files.

### 8. Breaking Down Complex Tasks

For complex tasks that need more granularity:

```
Task 5 seems complex. Can you break it down into subtasks?
```

The agent will execute:

```bash theme={null}
taskgraph expand --id=5 --num=3
```

You can provide additional context:

```
Please break down task 5 with a focus on security considerations.
```

The agent will execute:

```bash theme={null}
taskgraph expand --id=5 --prompt="Focus on security aspects"
```

You can also expand all pending tasks:

```
Please break down all pending tasks into subtasks.
```

The agent will execute:

```bash theme={null}
taskgraph expand --all
```

For research-backed subtask generation using the configured research model:

```
Please break down task 5 using research-backed generation.
```

The agent will execute:

```bash theme={null}
taskgraph expand --id=5 --research
```

## Example Claude Code Interactions

### Starting a new project

```
I've just initialized a new project with TaskGraph. I have a PRD at .taskgraph/docs/prd.md.
Can you help me parse it and set up the initial tasks?
```

### Working on tasks

```
What's the next task I should work on? Please consider dependencies and priorities.
```

### Implementing a specific task

```
I'd like to implement task 4. Can you help me understand what needs to be done and how to approach it?
```

### Managing subtasks

```
I need to regenerate the subtasks for task 3 with a different approach. Can you help me clear and regenerate them?
```

### Handling changes

```
We've decided to use MongoDB instead of PostgreSQL. Can you update all future tasks to reflect this change?
```

### Completing work

```
I've finished implementing the authentication system described in task 2. All tests are passing.
Please mark it as complete and tell me what I should work on next.
```

### Analyzing complexity

```
Can you analyze the complexity of our tasks to help me understand which ones need to be broken down further?
```

### Viewing complexity report

```
Can you show me the complexity report in a more readable format?
```

### Research-Driven Development

TaskGraph includes a powerful research tool that provides fresh, up-to-date information beyond the AI's knowledge cutoff. This is particularly valuable for:

#### Getting Current Best Practices

```
Before implementing task 5 (authentication), research the latest JWT security recommendations.
```

The agent will execute:

```bash theme={null}
taskgraph research "Latest JWT security recommendations 2024" --id=5
```

#### Research with Project Context

```
Research React Query v5 migration strategies for our current API implementation.
```

The agent will execute:

```bash theme={null}
taskgraph research "React Query v5 migration strategies" --files=src/api.js,src/hooks.js
```

#### Research and Update Pattern

A powerful workflow is to research first, then update tasks with findings:

```
Research the latest Node.js performance optimization techniques and update task 12 with the findings.
```

The agent will:

1. Run research: `taskgraph research "Node.js performance optimization 2024" --id=12`
2. Update the task: `taskgraph update-subtask --id=12.2 --prompt="Updated with latest performance findings: [research results]"`

#### When to Use Research

* **Before implementing any new technology**
* **When encountering security-related tasks**
* **For performance optimization tasks**
* **When debugging complex issues**
* **Before making architectural decisions**
* **When updating dependencies**

The research tool automatically includes relevant project context and provides fresh information that can significantly improve implementation quality.

## Git Integration and Tag Management

TaskGraph supports tagged task lists for multi-context development, which is particularly useful when working with git branches or different project phases.

### Working with Tags

Tags provide isolated task contexts, allowing you to maintain separate task lists for different features, branches, or experiments:

```
I'm starting work on a new feature branch. Can you create a new tag for this work?
```

The agent will execute:

```bash theme={null}
# Create a tag based on your current git branch
taskgraph tags add <name> --from-branch
```

Or you can create a tag with a specific name:

```
Create a new tag called 'user-auth' for authentication-related tasks.
```

The agent will execute:

```bash theme={null}
taskgraph tags add user-auth --description="User authentication feature tasks"
```

### Switching Between Contexts

When working on different features or branches:

```
Switch to the 'user-auth' tag context so I can work on authentication tasks.
```

The agent will execute:

```bash theme={null}
taskgraph tags use user-auth
```

### Copying Tasks Between Tags

When you need to duplicate work across contexts:

```
Copy all tasks from the current tag to a new 'testing' tag for QA work.
```

The agent will execute:

```bash theme={null}
taskgraph tags add testing --copy-from=master --description="QA and testing tasks"
```

### Tag Management

View and manage your tag contexts:

```
Show me all available tags and their current status.
```

The agent will execute:

```bash theme={null}
taskgraph tags --show-metadata
```

### Benefits of Tagged Task Lists

* **Branch Isolation**: Each git branch can have its own task context
* **Merge Conflict Prevention**: Tasks in different tags don't interfere with each other
* **Parallel Development**: Multiple team members can work on separate contexts
* **Context Switching**: Easily switch between different project phases or features
* **Experimentation**: Create experimental task lists without affecting main work

### Git Workflow Integration

A typical git workflow with TaskGraph tags:

1. **Create feature branch**: `git checkout -b feature/user-auth`
2. **Create matching tag**: Ask the agent to run `taskgraph tags add <name> --from-branch`
3. **Work in isolated context**: All task operations work within the new tag
4. **Switch contexts as needed**: Use `taskgraph tags use <name>` to switch between different work streams
5. **Merge and cleanup**: After merging the branch, optionally delete the tag with `taskgraph tags remove <name>`

This workflow ensures your task management stays organized and conflicts are minimized when working with teams or multiple features simultaneously.


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