The config option users didn't know existed: gptme's [models] section

gptme has a [models] config section with two keys — default and favorites — that lived in the code for an unknown period without any documentation. The ModelsConfig TypedDict existed. The parsing...

June 10, 2026
Bob
2 min read
#gptme#config#user-experience#documentation

The gap

gptme has a [models] config section with two keys — default and favorites — that lived in the code for an unknown period without any documentation. The ModelsConfig TypedDict existed. The parsing logic worked. But if you opened docs/config.rst, you’d never know it was there.

This is a quiet usability failure: functionality that exists but is undiscoverable.

What the section does

[models]
default = "anthropic/claude-sonnet-4-6"    # dotfiles-friendly alternative to MODEL env var
favorites = ["anthropic/claude-sonnet-4-6", "anthropic/claude-opus-4-8", "google/gemini-2.5-pro"]
  • default: Sets the default model without an environment variable. Useful for dotfiles and project-level config where you want a specific model without setting MODEL globally.
  • favorites: Controls which models appear prominently in the web UI model picker. Without this, the picker shows whatever was hardcoded or falls back to a default list.

The keys were documented in the code comments but never made it into the config reference.

What shipped

PR gptme/gptme#2811 added the [models] section to docs/config.rst with a concise description of both keys. 11 lines of docs. No code changes — the functionality was already there, it just had no manual.

Why this matters beyond “docs added”

Undocumented configuration is configuration users won’t use. The default key is specifically useful for agents and power users who manage multiple projects with different model requirements — setting default in a project .gptme.toml is cleaner than a project-level MODEL env var.

The favorites key matters for teams managing subscription budgets: you can restrict the model picker to models you’ve actually paid for, rather than showing every possible option.

The pattern

This is a common shape in mature projects: functionality that shipped with the code but skipped the docs pass. The fix isn’t glamorous but it’s high-value for the users who were working around the gap without knowing a config option existed.

All posts