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

# Configuration

> Configure TaskGraph models, defaults and environment variables

TaskGraph needs no API keys. It runs on your signed-in Claude Code. See [Authentication](https://taskgraph-ai.com/getting-started/api-keys.md).

Configuration lives in `.taskgraph/config.json`. Create or change it with `taskgraph models`, and avoid editing it by hand.

## Shared and per-machine settings

`.taskgraph/config.json` is shared: commit it so everyone on the project uses the same models and defaults. Settings that only make sense on one machine go in `.taskgraph/config.local.json`, which `taskgraph init` adds to `.gitignore`.

* TaskGraph reads `config.local.json` over `config.json`: any key in the local file wins, and objects merge key by key. A missing local file is fine.
* If `config.local.json` isn't valid JSON, TaskGraph warns, uses `config.json` alone, and leaves the file for you to fix.
* `claudeCode.pathToClaudeCodeExecutable` is always per-machine. TaskGraph saves it to `config.local.json`, and moves it there from `config.json` the next time it saves settings or `taskgraph init` runs.
* To use a different model on your machine only, put it in `config.local.json`, for example `{ "models": { "main": { "modelId": "opus" } } }`. From then on, `taskgraph models --set-main` and `--setup` save the main model there and leave the shared one alone.

`.taskgraph/state.json` holds your current tag and is gitignored too, so `taskgraph tags use` never changes a committed file.

## Models

Three roles, each set to one of `opus`, `sonnet` or `haiku`:

| Role | Used for |
| - | - |
| `main` | Task generation and updates |
| `research` | Research-backed operations (web search and fetch only; it cannot read or change your files and has no shell) |
| `fallback` | Any operation where the main or research call fails |

```bash theme={null}
taskgraph models                       # view the current configuration
taskgraph models --setup               # interactive setup
taskgraph models --set-main sonnet
taskgraph models --set-research opus
taskgraph models --set-fallback haiku
```

## Example `config.json`

```json theme={null}
{
  "models": {
    "main": { "provider": "claude-code", "modelId": "sonnet", "maxTokens": 64000, "temperature": 0.2 },
    "research": { "provider": "claude-code", "modelId": "sonnet", "maxTokens": 8700, "temperature": 0.1 },
    "fallback": { "provider": "claude-code", "modelId": "sonnet", "maxTokens": 64000, "temperature": 0.2 }
  },
  "global": {
    "logLevel": "info",
    "debug": false,
    "defaultNumTasks": 0,
    "defaultSubtasks": 5,
    "defaultPriority": "medium",
    "defaultTag": "master",
    "projectName": "Your Project Name",
    "responseLanguage": "English"
  },
  "claudeCode": {}
}
```

TaskGraph saves only the settings you change. A setting left out of `config.json` uses the current default, so it follows a new default after an upgrade.

Projects from before `defaultNumTasks` became `0` may have `"defaultNumTasks": 10` saved next to `"enableProxy": false`. That 10 was the old default, saved automatically, so TaskGraph removes both lines the next time it reads the file. To keep asking for about 10 tasks, set `defaultNumTasks` to `10` again or pass `--num-tasks 10`.

## Definition of Done

`global.definitionOfDone` lists checks every task must clear before `set-status done` accepts it, on top of the task's own acceptance criteria:

```json theme={null}
{
  "global": {
    "definitionOfDone": ["Tests pass", "Docs updated"]
  }
}
```

`taskgraph show <id>` numbers these after the task's own criteria. Check them per task with `taskgraph set-status <id> --check <n>`, or pass `--force` to skip the gate. Subtasks are not gated by the Definition of Done.

## Archiving finished tasks

`global.archiveAfterDays` (default `30`) is how long a done or cancelled task stays in tasks.json before `taskgraph archive` moves it to `.taskgraph/tasks/archive.json`. `--older-than <days>` overrides it for one run.

```json theme={null}
{
  "global": {
    "archiveAfterDays": 14
  }
}
```

See [Archiving finished tasks](https://taskgraph-ai.com/capabilities/archive.md) for how archived IDs and dependencies behave.

## Environment variables

| Variable | Description |
| - | - |
| `CLAUDE_CODE_API_KEY` | Optional. Bill Claude Code calls to this Anthropic API key instead of your Claude Code sign-in. |
| `TASKGRAPH_TOOLS` | Which MCP tools to load: `core` (default), `standard`, `all` or a comma-separated list. See [MCP tools](https://taskgraph-ai.com/capabilities/mcp.md). |
| `TASKGRAPH_MODEL_MAIN`, `TASKGRAPH_MODEL_RESEARCH`, `TASKGRAPH_MODEL_FALLBACK` | Override a model role. |
| `TASKGRAPH_RESPONSE_LANGUAGE` | Override the language of generated content. |
| `TASKGRAPH_TAG` | Override the active tag. |
| `TASKGRAPH_PROJECT_ROOT` | Project root, for tools that run outside the project folder. The CLI uses it when you don't pass `--project`, and the MCP server when a tool call passes no `projectRoot`: an explicit path wins, except a path inside this project's `.taskgraph/worktrees/` (a `loop --parallel` task worktree), which gives this project. `loop --parallel` sets it for each task's Claude Code process. |
| `TASKGRAPH_LOG_LEVEL` | Console log level. |
| `TASKGRAPH_DEBUG` | Set to `true` for debug logging. |

Model IDs, `maxTokens`, `temperature`, `defaultSubtasks`, `defaultPriority` and `projectName` belong in `config.json`, not in environment variables.

> [!NOTE]
>
> Upgrading? Variables named `TASK_MASTER_*` and `TASKMASTER_*` were renamed to `TASKGRAPH_*` in 0.47, and the old names are ignored. See the [upgrade guide](https://taskgraph-ai.com/upgrading.md).

## Troubleshooting

### If `taskgraph init` doesn't respond

Run the CLI through npx instead:

```bash theme={null}
npx -y -p taskgraph-ai taskgraph init
```

### Configuration errors

If TaskGraph cannot find its config file, run `taskgraph models --setup` in your project root to create or repair it.

For tag, timeout and MCP details, see the [Advanced Configuration Guide](https://taskgraph-ai.com/best-practices/configuration-advanced.md).


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