Configuration

TaskGraph needs no API keys. It runs on your signed-in Claude Code. See Authentication. 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

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`

{
  "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:

{
  "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.

{
  "global": {
    "archiveAfterDays": 14
  }
}

See Archiving finished tasks 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.
`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.

Upgrading? Variables named TASK_MASTER_* and TASKMASTER_* were renamed to TASKGRAPH_* in 0.47, and the old names are ignored. See the upgrade guide.

Troubleshooting

If `taskgraph init` doesn’t respond

Run the CLI through npx instead:

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.

Welcome

Getting Started

Best Practices

Technical Capabilities

Shared and per-machine settings

Models

Example `config.json`

Definition of Done

Archiving finished tasks

Environment variables

Troubleshooting

If `taskgraph init` doesn’t respond

Configuration errors

​Shared and per-machine settings

​Models

​Example config.json

​Definition of Done

​Archiving finished tasks

​Environment variables

​Troubleshooting

​If taskgraph init doesn’t respond

​Configuration errors

Shared and per-machine settings

Models

Example `config.json`

Definition of Done

Archiving finished tasks

Environment variables

Troubleshooting

If `taskgraph init` doesn’t respond

Configuration errors