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

# Claude Code Integration

> How TaskGraph uses Claude Code for every AI operation, and the advanced settings it exposes

TaskGraph runs every AI operation through the Claude Code CLI. There are no provider accounts and no API keys to manage. This page covers authentication, models and the advanced Claude Code settings.

## Authentication

TaskGraph uses whatever sign-in Claude Code already has.

1. Install [Claude Code](https://docs.claude.com/en/docs/claude-code) and run `claude` once to sign in.
2. That is all. `taskgraph` commands and the MCP server now work.

Optional overrides, in the order TaskGraph considers them:

| Variable | When to use it |
| - | - |
| `CLAUDE_CODE_API_KEY` | Bill TaskGraph's calls to a specific Anthropic API key. When set it is used exclusively. |
| `CLAUDE_CODE_OAUTH_TOKEN` | Headless environments such as CI or containers. Create a token with `claude setup-token`. |

When neither is set, TaskGraph withholds `ANTHROPIC_API_KEY` from Claude Code so that Claude Code uses its own sign-in. See [Authentication](https://taskgraph-ai.com/getting-started/api-keys.md).

## Models

Each of the three roles (`main`, `research`, `fallback`) uses `opus`, `sonnet` or `haiku`:

```bash theme={null}
taskgraph models --set-main sonnet
taskgraph models --set-research opus
taskgraph models --set-fallback haiku
taskgraph models --setup
```

Or edit the roles in `.taskgraph/config.json`:

```json theme={null}
{
  "models": {
    "main": { "provider": "claude-code", "modelId": "sonnet", "maxTokens": 64000, "temperature": 0.2 },
    "research": { "provider": "claude-code", "modelId": "opus", "maxTokens": 32000, "temperature": 0.1 },
    "fallback": { "provider": "claude-code", "modelId": "sonnet", "maxTokens": 64000, "temperature": 0.2 }
  }
}
```

## What AI calls can access

Each AI call is confined by its role. Your project's own Claude setup, a prompt in a task or PRD, and TaskGraph's own config cannot widen what a call can do.

| | `main` / `fallback` | `research` |
| - | - | - |
| Tools | `Read`, `Grep`, `Glob` | `WebSearch`, `WebFetch` |
| Shell, edit and write tools | Denied | Denied |
| MCP servers | None | None |
| Your Claude settings, hooks and `CLAUDE.md` | Not loaded | Not loaded |
| Files | The project root only (none if TaskGraph can't find the project) | None |
| Permission prompts | Never shown; anything not allowed is denied | Same |
| Turn limit | Claude Code's default | 8, unless `maxTurns` is set |

In practice:

* **Your Claude Code setup stays out.** Hooks, `CLAUDE.md`, permission rules and MCP servers from your user, project and local Claude settings are not loaded, so they don't run inside TaskGraph's calls.
* **File reads stay in the project.** For `main` and `fallback`, a `PreToolUse` hook refuses any `Read`, `Grep` or `Glob` whose path resolves outside the project root. Symlinks are resolved first, so a link in the repo that points elsewhere is refused, as are `..` segments, `~` paths, absolute paths and glob patterns that climb out.
* **Secret files stay closed.** The same hook refuses a `Read`, `Grep` or `Glob` that names one of these (any letter case):

  * env files: `.env`, `.env.*`, `.env-*`, `.env_*`, `.envrc`. `.env.example`, `.env.sample` and `.env.template` (or with `-`/`_`) can still be read.
  * keys and certificates: `*.pem`, `*.key`, `*.p12`, `*.pfx`, `*.keystore`, `*.jks`, PuTTY's `*.ppk`, and `id_rsa`, `id_dsa`, `id_ecdsa`, `id_ed25519` and their `.pub` files.
  * credential stores: `.git`, `.git-credentials` and `.config/git/credentials`, `.npmrc`, `.netrc`, `_netrc`, `.pypirc`, `.pgpass` and its Windows name `pgpass.conf`, the whole `.aws` and `.kube` directories, kubeconfigs kept elsewhere (`kubeconfig`, `*.kubeconfig`), and `.docker/config.json`.

  A `Grep` over a whole directory is rewritten to skip those files, so a search for `API_KEY` across the project can't return lines from `.env`. Its `path` is rewritten to the resolved absolute path, so `.docker//`, `src/../.docker` or a symlink to `.docker` skips `.docker/config.json` just as `.docker` does. A search path that Windows or macOS would open as `.docker`, `.config` or `git` under another spelling (`.docker.`, a trailing space, a Kelvin sign `K` for `k`, a dotless `ı` for `i`) is refused. That search also skips `.env.example`. Other spellings that Windows or macOS open as one of these are refused too: an alternate data stream (`.env::$DATA`), a trailing dot or space (`.env.`, `.env `), any 8.3 short name such as `ENV~1`, and non-ASCII letters a case-insensitive filesystem matches to ASCII (`.awſ`, with a long s, can open `.aws`).
* **Config can't widen it.** The settings below are applied first and these limits after, so config can't add tools or MCP servers, load settings sources, add directories or replace the hook. `pathToClaudeCodeExecutable` is only used when it's an absolute path to a file named `claude` outside the project, so a repo's config can't point it at another program.

What this doesn't cover:

* Secret files are recognized by name only. A key saved as `config/prod.json` or a token pasted into a source file can be read and sent to the model.
* The path check runs just before each tool call. A symlink swapped by another process between the check and the read isn't caught; nothing in the call itself can write.
* It's a check on Claude Code's file tools, not an OS sandbox. It relies on shell tools being denied.
* For `Grep`, only `path` and `glob` are checked. Its regex only filters lines, and `glob` only filters files under that path, so neither can reach outside it.
* The project root is the one TaskGraph uses for the command: `--project-root` if you pass it, otherwise the project it finds from the current directory. If that's a parent of several projects, all of them are readable. If no root is found, `main` and `fallback` get no file tools.

## Structured outputs

Commands that generate structured data (`parse-prd`, `add-task`, `expand`, `update`, `update-task`, `analyze-complexity`) use Claude Code's native structured output support. Responses are constrained to the expected schema, so there are no JSON parsing retries.

## Advanced settings

Claude Code settings can be set globally in the `claudeCode` section of `.taskgraph/config.json`, or per command in `commandSpecific`. Command-specific settings override global ones.

```json theme={null}
{
  "claudeCode": {
    "maxTurns": 5,
    "customSystemPrompt": "You are a helpful assistant focused on code quality",
    "appendSystemPrompt": "Always follow coding best practices"
  },
  "commandSpecific": {
    "parse-prd": {
      "maxTurns": 10,
      "customSystemPrompt": "You are a task breakdown specialist"
    },
    "analyze-complexity": {
      "maxTurns": 3,
      "appendSystemPrompt": "Focus on identifying bottlenecks"
    }
  }
}
```

| Setting | Purpose |
| - | - |
| `maxTurns` | Maximum conversation turns in a single request. Useful for complex multi-step operations. |
| `customSystemPrompt` | Replaces Claude Code's system prompt to specialize behavior. |
| `appendSystemPrompt` | Adds standards or context to the system prompt. |
| `pathToClaudeCodeExecutable` | Absolute path to the `claude` executable if it is not on your `PATH`. It must be named `claude` (`claude.exe` or `claude.cmd` on Windows) and live outside the project, or it's ignored with a warning. It differs per machine, so set it in the gitignored `.taskgraph/config.local.json` (see [Shared and per-machine settings](https://taskgraph-ai.com/configuration.md#shared-and-per-machine-settings)). |

Tools, permission mode, MCP servers, settings sources, working directory, extra directories and hooks are set by the role and can't be changed here. See [What AI calls can access](#what-ai-calls-can-access).

## Notes

* Claude Code does not report usage costs, so cost shows as 0 in telemetry.
* `temperature` and `maxTokens` are not supported by the Claude Code CLI and may be ignored.

## Troubleshooting

### "Claude Code CLI not available"

* Install it with `npm install -g @anthropic-ai/claude-code` and make sure `claude` is on your `PATH`.
* Verify it works by running `claude --help`.

### Authentication failures

* Run `claude` and sign in again.
* In CI or containers, run `claude setup-token` and pass the result as `CLAUDE_CODE_OAUTH_TOKEN`.

### Unknown model

Use one of `opus`, `sonnet` or `haiku`. Run `taskgraph models` to see the current configuration.


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