Claude Code Integration

​

Authentication

1. Install Claude Code and run claude once to sign in.
2. That is all. taskgraph commands and the MCP server now work.

​

Models

taskgraph models --set-main sonnet
taskgraph models --set-research opus
taskgraph models --set-fallback haiku
taskgraph models --setup

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

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

• 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

​

Advanced settings

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

​

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