Config Files

Geoff Code splits configuration into two TOML files under ~/.geoff (or $GEOFF_CODE_HOME if set):

File	Owns
`config.toml`	Agent and runtime settings — providers, models, permissions, hooks, loop control.
`tui.toml`	Client preferences — terminal theme, editor, notifications, auto-update.

Both are created with defaults on first run. Validate them at any time with geoff doctor (see Command Reference). Keys use snake_case.

config.toml

Top-level keys

Key	Type	Description
`default_model`	string	Model alias to use when `-m` isn’t passed. Defaults to `pyro`.
`default_provider`	string	Provider to use when a model doesn’t name one.
`default_thinking`	bool	Enable thinking mode by default.
`default_permission_mode`	string	`manual`, `auto`, or `yolo`.
`default_plan_mode`	bool	Start sessions in plan mode (read-only tools).
`yolo`	bool	Auto-approve all actions by default.
`merge_all_available_skills`	bool	Merge every skill directory instead of resolving by priority.
`extra_skill_dirs`	string[]	Extra skill directories to load.
`telemetry`	bool	Toggle anonymous usage telemetry.

`[providers.<name>]`

Each provider declares how to reach an API. The type is one of anthropic, openai, openai_responses, google-genai, vertexai, or kimi.

[providers.geoff]
type = "anthropic"
base_url = "https://geoff.ai/api"
api_key = "${GEOFF_API_KEY}"

Field	Description
`type`	Required. Provider protocol.
`base_url`	API endpoint.
`api_key`	API key (prefer referencing an env var).
`default_model`	Default model for this provider.
`env`	Map of extra environment variables.
`custom_headers`	Map of HTTP headers to add to every request.

Get a key from https://geoff.ai/settings/api-keys. Avoid committing keys; set GEOFF_API_KEY in your environment, or pass -k, --api-key for a single invocation.

`[models.<alias>]`

Aliases map a short name to a concrete model on a provider. The default alias is pyro.

[models.pyro]
provider = "geoff"
model = "pyro-1m"
max_context_size = 1000000
display_name = "Pyro"
capabilities = ["thinking", "image_in"]

Field	Required	Description
`provider`	yes	Name of a defined provider.
`model`	yes	Model identifier passed to the API.
`max_context_size`	yes	Context window in tokens (must be positive).
`max_output_size`	no	Max output tokens.
`capabilities`	no	Feature tags, for example `thinking`, `image_in`.
`display_name`	no	Human-readable label shown in the TUI.

`[[hooks]]`

Lifecycle hooks (array of tables). See Hooks for events and the I/O protocol.

[[hooks]]
event = "PostToolUse"
matcher = "WriteFile|StrReplaceFile"
command = "jq -r '.tool_input.file_path' | xargs prettier --write"
timeout = 10

`[permission]`

Persistent allow/deny/ask rules for tool calls.

[[permission.rules]]
decision = "allow"      # allow | deny | ask
scope = "user"          # turn-override | session-runtime | project | user
pattern = "Bash(git status)"

`[loop_control]`

Tune the agent’s turn-execution limits.

[loop_control]
max_steps_per_turn = 1000
max_retries_per_step = 3
reserved_context_size = 50000
compaction_trigger_ratio = 0.85   # 0.5–0.99

`[background]`

Control background task execution.

[background]
max_running_tasks = 4
keep_alive_on_exit = false
kill_grace_period_ms = 2000

`[experimental]`

Toggle named experimental features (booleans). Unknown keys are rejected by validation.

[experimental]
goal_command = true

Alternate config files

Geoff Code also reads config.toml over RPC at startup. Use geoff doctor config <path> to validate a file at a non-default path.

tui.toml

Client-side preferences for the terminal UI:

# ~/.geoff/tui.toml

theme = "auto"   # "auto" | "dark" | "light"

[editor]
command = ""     # empty uses $VISUAL / $EDITOR

[notifications]
enabled = true
notification_condition = "unfocused"   # "unfocused" | "always"

[upgrade]
auto_install = true

Key	Default	Description
`theme`	`auto`	Terminal color theme.
`editor.command`	`""`	External editor command; empty falls back to `$VISUAL` / `$EDITOR`.
`notifications.enabled`	`true`	Toggle desktop notifications.
`notifications.notification_condition`	`unfocused`	When to notify: only when unfocused, or always.
`upgrade.auto_install`	`true`	Auto-install new versions.

Validate it with geoff doctor tui.

Command Reference

Use geoff doctor to validate both files.

Hooks

The full hook event reference.

Getting Started

Extending

Reference

config.toml

Top-level keys

`[providers.<name>]`

`[models.<alias>]`

`[[hooks]]`

`[permission]`

`[loop_control]`

`[background]`

`[experimental]`

Alternate config files

tui.toml

Command Reference

Hooks

​config.toml

​Top-level keys

​[providers.<name>]

​[models.<alias>]

​[[hooks]]

​[permission]

​[loop_control]

​[background]

​[experimental]

​Alternate config files

​tui.toml

​Related

Command Reference

Hooks

config.toml

Top-level keys

`[providers.<name>]`

`[models.<alias>]`

`[[hooks]]`

`[permission]`

`[loop_control]`

`[background]`

`[experimental]`

Alternate config files

tui.toml

Related