Configuration

Tau loads configuration from two YAML files, merged in order (later wins):

1. Global: ~/.config/tau/config.yaml
2. Project-local: .tau.yaml (in the current working directory)

Config Structure

type Config struct {
    DefaultProvider string                    `yaml:"default_provider"`
    DefaultModel    string                    `yaml:"default_model"`
    Providers       []ProviderConfig          `yaml:"providers"`
    UI              UIConfig                  `yaml:"ui"`
    Debug           bool                      `yaml:"debug"`
    Plugins         map[string]map[string]any `yaml:"plugins"`
}

ProviderConfig

type ProviderConfig struct {
    Name    string            `yaml:"name"`
    Type    string            `yaml:"type,omitempty"`
    BaseURL string            `yaml:"base_url"`
    Auth    AuthConfig        `yaml:"auth"`
    Headers map[string]string `yaml:"headers,omitempty"`
}

type AuthConfig struct {
    Type      string `yaml:"type"`        // "api_key", "none", "oauth_pkce"
    APIKeyEnv string `yaml:"api_key_env"` // env var for API key
    APIKey    string `yaml:"api_key"`     // literal key; prefer api_key_env
}

Auth Types

Type	Description
api_key	Static API key from environment variable (api_key_env)
none	No credential required
oauth_pkce	Browser OAuth PKCE for hand-written config providers

Tau-managed catalog OAuth logins, currently github-copilot and openai-codex, are handled with /provider login <name> and persisted in ~/.config/tau/auth.yaml, not in config.yaml.

UIConfig

type UIConfig struct {
    ShowReasoning bool `yaml:"show_reasoning"` // default: false
}

Controls terminal UI presentation:

• show_reasoning: true - display reasoning/chain-of-thought content.

Plugin Config

The plugins section is free-form YAML passed through to plugins by name:

plugins:
  my-plugin:
    api_key_env: MY_PLUGIN_API_KEY
    endpoint: https://api.example.com

Tau does not validate or interpret plugin config - each plugin parses its own section.

Updates

The updates section controls how tau checks for new releases:

updates:
  mode: warn

updates.mode	Behavior
warn (default)	tau update works; tau may notify when an update is available.
disabled	No update checks at all — tau update is also disabled.
auto (reserved)	Accepted but behaves as warn with a logged warning. Reserved for future background auto-update.

Note: Dev builds (go build from source, version dev) are always excluded from update checks. Only release builds downloaded from GitHub releases are eligible. See tau update --help for the manual update flow.

Example Configurations

Minimal (API Key)

default_provider: deepseek
default_model: deepseek-v4-flash

providers:
  - name: deepseek
    base_url: https://api.deepseek.com
    auth:
      type: api_key
      api_key_env: DEEPSEEK_API_KEY

Multiple Providers

default_provider: openai
default_model: gpt-5.5

providers:
  - name: openai
    auth:
      type: api_key
      api_key_env: OPENAI_API_KEY

  - name: anthropic
    auth:
      type: api_key
      api_key_env: ANTHROPIC_API_KEY

  - name: ollama
    base_url: http://localhost:11434/v1

ui:
  show_reasoning: true

With Plugin Config

default_provider: openrouter
default_model: openai/gpt-5.5

providers:
  - name: openrouter
    base_url: https://openrouter.ai/api/v1
    auth:
      type: api_key
      api_key_env: OPENROUTER_API_KEY

plugins:
  github:
    token_env: GITHUB_TOKEN
    poll_interval: 5m

Environment Variables

Variable	Purpose
TAU_PROVIDER	Default provider (overrides config)
TAU_INSECURE	Skip TLS verification
TAU_VERBOSE	Enable verbose logging
TAU_MODELS_CATALOG_URL	Override models.dev catalog URL
TAU_MODELS_CATALOG_TTL	Override catalog cache TTL
TAU_SCHEDULE_INTERVAL	Set plugin schedule tick interval
Provider-specific *_API_KEY	API key for each provider (configured in api_key_env)

CLI Flags

CLI flags override configuration:

Flag	Config Equivalent
--provider <name>	default_provider
--model <id>	default_model
--max-tokens <n>	Session parameter
--temperature <f>	Session parameter
--web	Start web UI + open browser
--port <n>	Web UI port (0 = auto)
--no-web	Disable web UI
--insecure	TAU_INSECURE
--verbose	TAU_VERBOSE
--prompt <text>	One-shot stdin mode
--resume <id>	Resume saved session

Config Resolution

1. Load ~/.config/tau/config.yaml.
2. If ./.tau.yaml exists, merge it (project values override global).
3. Apply environment variable overrides.
4. Apply CLI flag overrides.

The merge is a shallow merge at the top level. Provider lists are merged by name - a provider in .tau.yaml with the same name as one in config.yaml replaces it entirely.

Models.dev Catalog

Model metadata (context windows, pricing, capabilities) comes from the models.dev catalog, cached at ~/.config/tau/models.json. See Providers for details.

Catalog Overrides

Create ~/.config/tau/api.overrides.json to override model metadata:

{
  "providers": {
    "deepseek": {
      "models": {
        "deepseek-v4-flash": {
          "output": 16384
        }
      }
    }
  }
}

Refresh the catalog with tau refresh or /refresh in the TUI.

Config Directory

Tau's config directory is ~/.config/tau/:

~/.config/tau/
├── config.yaml           # Global config
├── auth.yaml             # Managed provider credentials (API keys, OAuth tokens)
├── models.json           # models.dev catalog cache
├── api.overrides.json    # Model metadata overrides (optional)
├── sessions.db           # SQLite session store
├── plugins/              # Plugin binaries
├── commands/             # User custom commands
├── skills/               # User skills
└── tau.log               # Application logs

API keys entered via tau setup or tau provider login are stored in auth.yaml, not config.yaml, so hand-edited config never contains secrets. See Providers > Credential Sources for details on managed keys vs env vars vs OAuth.

Programmatic Access

The config package (internal/config) provides:

func Dir() string                           // ~/.config/tau
func GlobalPath() string                    // ~/.config/tau/config.yaml
func LocalPath() string                     // ./.tau.yaml
func SessionsDir() string                   // ~/.config/tau/sessions
func SessionsDBPath() string                // ~/.config/tau/sessions.db
func LoadConfig() (*Config, error)          // Load global config
func LoadConfigFrom(paths ...string) (*Config, error) // Load from custom paths
func ResolveProvider(config, name) (ProviderConfig, error)
func ProviderNames(config) []string
func (c *Config) Validate() error

YAML field names support both kebab-case and camelCase variants.