Configuration overview¶

gdc reads its settings from TOML configuration files, with environment variables and command-line flags able to override them. This page explains where settings come from and which wins; the Reference lists every setting, and Examples shows ready-to-use snippets.

Where configuration lives¶

gdc merges up to three files, in this order (later wins):

User — ~/.gdc/config.toml
User (XDG) — $XDG_CONFIG_HOME/gdc/config.toml, typically ~/.config/gdc/config.toml
Project — <project>/.gdc/config.toml

So a project-local file overrides your personal settings, which is what you usually want: shared defaults per user, with per-project tweaks checked into the repository.

You can also point gdc at a specific file explicitly:

gdc --config /path/to/config.toml ...

Bad files are skipped, not fatal

If a config file can't be parsed, gdc warns and continues with the settings it could load, rather than refusing to start. Unknown keys are reported so typos don't pass silently.

What overrides what¶

From lowest to highest priority:

config files  <  environment variables  <  command-line flags

The most common settings have all three forms:

Setting	Flag	Environment variable	Config
Endpoint	`--base-url`	`GDC_BASE_URL`	`[provider].base_url`
Model	`--model`	`GDC_MODEL`	`[provider].model`
API key	`--api-key`	`GDC_API_KEY`	`[provider].api_key`
Config file	`--config`	`GDC_CONFIG`	—
Session database	`--db-path`	`GDC_DB_PATH`	`[storage].path`
Session id	`--session-id`	`GDC_SESSION_ID`	—

→ Environment variables

A minimal config¶

The only thing most people need to set is how to reach a model:

~/.gdc/config.toml

[provider]
base_url = "http://localhost:11434/v1"
model    = "qwen2.5-coder:14b-instruct"

Everything else has sensible defaults; add sections only when you want to change something.

Editing configuration¶

By hand — open the file in your editor. Paths use ~ for your home directory, which gdc expands.
In the terminal app — the /config screen edits common settings and saves them for you.
With commands — gdc mcp add, for example, edits the [mcp.servers] section while preserving your comments and formatting.

What you can configure¶

The Reference covers every section. The highlights:

Section	Controls
`[provider]`	Model endpoint, model name, API key, named profiles.
`[permissions]`	Allow/deny rules for commands and file paths.
`[storage]`	Where sessions are saved.
`[mcp.servers]`	External tool servers.
`[memory]`	Persistent memory behavior.
`[hooks]`	Custom event handlers.
`[tui]`	Terminal-app theme and notifications.
`[output_styles]`	Default reply style.
`[task]`	Multi-agent limits.
`[swarm]`	Distributed TLS settings.