Configuration

config.toml, section by section

Config is layered TOML — later wins, tables deep-merge:

1. ~/.config/graph/config.toml (global)
2. ./.graph/config.toml (project)
3. Environment variables (GRAPH_STORAGE, GRAPH_LOG)
4. CLI flags

${VAR} in any string value resolves from the environment at load time. An unset variable never silently becomes an empty string — but when it errors depends on where it sits:

• Inside [providers.*] or [mcp.*] the error is deferred to the moment that provider or server is actually used: the value keeps its literal ${VAR} text, everything that doesn’t need the secret (plan authoring, listing, graph mcp serve, key-free plans) keeps working, and the first call that does need it fails naming the variable and the config path that references it.
• Anywhere else (paths, prompts, settings) an unset variable still fails the load immediately — a data_dir carrying literal ${VAR} text would be silently wrong everywhere.

[settings]

[settings]
data_dir = "~/.local/share/graph"   # where threads and the shape cache live
max_agent_iterations = 15           # agent-loop tool rounds per turn
planning_attempts = 2               # plan_and_execute replan budget

[providers.*]

[providers.anthropic]
type = "anthropic"                  # anthropic | openai | openai_compat | bedrock
api_key = "${ANTHROPIC_API_KEY}"

[providers.local]
type = "openai_compat"
base_url = "http://localhost:11434/v1"    # Ollama, vLLM, LM Studio…

[providers.bedrock]                 # roadmap
type = "bedrock"
region = "us-east-1"
profile = "default"

Provider behavior — structured-output mechanisms, retries, and the bedrock roadmap status — is covered in Models & providers.

[models] — per-role assignment

Each pipeline role resolves to a model, falling back to default:

[models]
default = { provider = "anthropic", model = "claude-sonnet-5" }
chat    = { provider = "anthropic", model = "claude-sonnet-5" }
planner = { provider = "anthropic", model = "claude-sonnet-5" }
solver  = { provider = "anthropic", model = "claude-haiku-4-5", temperature = 0.4 }
repair  = { provider = "anthropic", model = "claude-haiku-4-5" }

Role	Used for
chat	the agent loop (ask/chat)
planner	plan_and_execute plan authoring
solver	plan report synthesis
repair	one-shot JSON repair when structured output fails to parse
judge	yes/no verdicts for inferred exit gates

Where each role fires, and the usual cost setup, are in Models & providers.

fallbacks — provider failover

Any model entry (a role or a named model) can carry an ordered list of failover candidates, used when its provider is having an outage:

[models.chat]
provider = "anthropic"
model = "claude-sonnet-5"
fallbacks = [
    { provider = "openai", model = "gpt-5" },
    { provider = "local", model = "llama3", temperature = 0.3 },
]

Each candidate names its own provider and model; temperature optionally overrides. Every referenced provider must exist under [providers] (checked at startup). When failover triggers, what carries over, and where fallbacks apply are in Models & providers.

[models.named] — named models

Beyond the fixed roles, any number of named models — referenceable wherever a model name is accepted: a prompt tool’s model field, or builtin__infer’s model input.

[models.named.nano]
provider = "anthropic"
model = "claude-haiku-4-5"
description = "fast and cheap; small self-contained tasks like per-item map bodies"

The description is a planner-facing routing signal, and names resolve in exactly three places — the full story, including the no-shadowing and no-silent-fallback rules, is in Models & providers.

[mcp.*]

See MCP servers for full detail.

[mcp.<name>]
command = "…"            # stdio — XOR with url
args = ["…"]
env = { KEY = "${VAR}" }
url = "https://…"        # streamable HTTP
headers = { Authorization = "Bearer ${VAR}" }
include_tools = ["…"]    # optional allowlist
exclude_tools = ["…"]    # optional blocklist

[mcp.<name>.tool_overrides.<tool>]
description = "…"
output_schema = { … }    # declare shapes the server omits
output_example = { … }   # optional worked example, shown to the planner

[plans] and [tools]

[plans]
paths = ["./.graph/plans", "~/.config/graph/plans"]

[tools]
paths = ["./.graph/tools", "~/.config/graph/tools"]
packs = []              # bundled tool packs to enable, e.g. ["github", "slack"]

packs enables the opt-in built-in tool packs — tool definitions that ship inside the binary, served under the builtin__ namespace. The llm and data packs are always on; packs adds the rest (github, slack).

[storage]

[storage]
backend = "file"        # default: plain files under data_dir
# backend = "memory"    # ephemeral (CI); or GRAPH_STORAGE=memory

[user]

Injected into the agent’s and planner’s context:

[user]
name = "Tyler"
context = "CEO and technical architect of LaunchNotes. Primary Linear team: LaunchNotes."
timezone = "America/Chicago"

[prompts]

System-prompt overrides. Each field replaces the built-in text wholesale; leave a field unset (or delete it) to keep the default. For additive context, use [user].context instead.

graph config init writes this section out pre-filled with the built-in defaults, so the usual starting point is editing those in place. A field left in the file pins that prompt at the written text — delete it to track the shipped default across releases.

[prompts]
# Base system prompt for the chat/ask agent loop. The current date/time
# and the [user] name/context are still appended after it.
chat = """
You are graph, a command-line assistant for release engineering.
Lead with the answer; keep formatting terminal-friendly.
"""

# Addendum appended to the chat prompt inside `graph workbench`.
workbench = """
# Plan workbench
Operate on the draft plan with the workbench__* tools...
"""

The workbench override is the agent’s only description of the workbench__* tools — how to draft, edit, validate, run, and save the plan in the side pane. Start from the built-in text (written into the file by graph config init) rather than writing from scratch, or the agent will stop using the workbench correctly.

[workbench]

[workbench]
log_path = "~/logs/graph-workbench.log"   # default: <data_dir>/workbench.log

Where the workbench’s debug log is written (tilde-expanded). The GRAPH_WORKBENCH_LOG environment variable overrides both.