internal/config both defined the types every package imports and performed
the file I/O to produce them. Importing a settings struct therefore pulled
in a TOML decoder and a YAML decoder, and the shared model owned discovery,
decoding, overlays, defaulting and validation all at once. See
docs/architecture/configuration.md, which requires loading to move out and
internal/config to be dissolved.
internal/config is now types only -- no os, no filepath, no toml. The new
package owns loading, one concern per file:
features.go the closed set of recognised feature files
discovery.go directory scan and classification
decode.go TOML/YAML decoding, format dispatch
defaults.go filling absent values, no errors
validate.go judging supplied values, no mutation
provenance.go which file contributed what
loader.go Loader wiring the above; File/Overlay/Dir
Beyond relocating, this fixes what the old code conflated:
- Defaulting and validation were interleaved. applyAgentDefaults and
applyDispatchDefaults returned validation errors; validateContainers and
validateSingleIdentity quietly mutated the config. There was no point at
which you could see what the operator actually supplied. They are now
separate passes: applyDefaults never fails, validate never writes.
- Errors were fmt.Errorf strings prefixed "config: ", so a caller could not
distinguish operator-fixable input from an unreadable file without
matching message text. Five sentinels now carry that distinction.
- dataHome() read XDG_DATA_HOME directly and discarded the error from
os.UserHomeDir, so defaulting could not be tested without the
environment. It is injectable on Loader and no longer swallows the error.
- Nothing recorded where a value came from. With overlays, feature files
and conf.d/ all able to set the same field, "which file set this?" was
answerable only by re-deriving precedence by hand. Provenance records it.
- Feature files were applied in map iteration order, making load order and
any resulting error arbitrary. Discovery now returns them sorted.
- loadMainConfig reported "no config.yaml or config.toml found in %s" with
an empty string: the directory was lost when it was extracted from
loadDirInto, so the error named no directory.
- Unreadable or malformed conf.d/ extras were skipped silently, which
presents as a setting the operator wrote simply not taking effect.
- Decode errors from the main config were returned bare, without naming
the file that failed to parse.
The 40 loader tests moved with the code and their assertions are unchanged,
so the defaulting and validation rewrite is behaviour-preserving.
Document.Config is the temporary seam: still internal/config.Config, named
as a field so the compromise is visible at each use site, with its deletion
condition recorded in doc.go. Building typed per-domain sections now, while
every consumer still reads config.Config, would mean two shapes kept in sync
by hand with no consumer for the new one; that belongs with the dissolution
work, not ahead of it.
No consumer outside cmd/archied changed.
Verified: go build, go vet, gofmt clean; go test ./internal/config/... and
./internal/infrastructure/configuration/... pass. Pre-existing gateway and
telegram failures are unchanged.
Tau CLI Reference
Tau is a provider-agnostic coding agent with an interactive terminal UI. It provides an extensible, personalised environment for working with AI models, featuring an interactive TUI, an optional Web UI, session history, token tracking, and plugin integration.
Usage
tau [global flags] [command]
Running tau with no arguments starts an interactive chat session and also starts a local Web UI on 127.0.0.1. You do
not need a --model flag; if no model is configured the session starts unselected and you pick one with /model.
Global Flags
| Flag | Description |
|---|---|
--provider <name> |
Provider name to use (e.g. deepseek, openrouter). Env: TAU_PROVIDER |
--model <id> |
Model ID to use. Also accepts provider:model-id or provider/model-id |
--max-tokens <n> |
Maximum completion tokens per response |
--temperature <f> |
Sampling temperature (0–2) |
--resume, -r <id|latest> |
Resume a saved session by ID, or latest |
--execute, -x <text> |
Execute mode: process prompt, print response, exit (reads stdin when piped) |
--prompt, -p <text> |
[deprecated] Use -x/--execute instead. One-shot / execute mode |
--jsonl, --stream-json |
Output framed JSONL events on stdout instead of plain text (execute mode) |
--child |
Run as a headless agent child process (internal use; hidden) |
--web |
Start the Web UI and open it in the default browser |
--port <n> |
HTTP port for the Web UI. Default 0 = OS-assigned ephemeral port |
--no-web |
Do not start the Web UI. TUI only |
--insecure |
Skip TLS certificate verification. Env: TAU_INSECURE |
--verbose |
Show debug messages on stderr. Env: TAU_VERBOSE |
Enabling Providers
Tau discovers providers automatically. To enable a provider:
-
tau setup(recommended for first run): Interactive walkthrough for selecting a provider and authenticating. Managed API keys are stored in~/.config/tau/auth.yaml— env vars override them when both are present. -
tau providerCLI:tau provider list # show all providers and auth state tau provider login deepseek # enter and store a managed API key tau provider login openai-codex # OAuth device-code flow tau provider login # interactive selector (TTY only) tau provider logout openai # disable and clear credentialsFor non-OAuth providers,
tau provider loginstores a managed API key inauth.yaml. -
Environment variable: Export the provider's API key env var (e.g.
DEEPSEEK_API_KEY=sk-...). Tau detects it at startup. -
TUI slash commands:
/provider [name]to toggle a provider,/provider login <name>for OAuth flow. -
config.yaml: Add a provider block (see Configuration below).
Run /model in the TUI to pick from all enabled providers' models.
Web UI
When tau starts interactively, it binds a local HTTP/WebSocket server on 127.0.0.1. The URL is shown in the TUI status
bar.
./tau # TUI + Web UI, URL in status bar
./tau --web # TUI + Web UI, also opens the browser
./tau --no-web # TUI only
./tau --port 9343 # Fixed port
The browser connects to /ws and receives the same event stream as the TUI. Commands sent from the browser are
forwarded to the coordinator identically to TUI commands. Multiple browser tabs may connect to the same session.
Slash Commands (TUI)
| Command | Description |
|---|---|
/model [id] |
Switch model; opens picker when called without an ID |
/provider [name] |
Toggle a provider on/off; lists all providers when called without an argument |
/provider login <provider> |
OAuth device-code sign-in for github-copilot or openai-codex; opens the browser and copies the code when possible |
/provider logout <provider> |
Disable a provider / remove its saved key |
/refresh |
Re-discover models from all enabled providers |
/effort [level] |
Set reasoning effort (off, low, medium, high, max) |
/reasoning [on|off] |
Toggle display of model reasoning content |
/system <prompt> |
Set the session system prompt |
/session [list|info|export|delete|<id>] |
Manage saved sessions |
/resume [id] |
Resume a saved session |
/new |
Start a fresh conversation (aliases: /clear, /reset) |
/reload |
Reload extensions/plugins |
/help |
Show all available commands |
/exit |
Quit tau |
Subcommands
tau setup
Interactive setup wizard for first-run configuration. Walks through provider selection, authentication (API key or OAuth), and model selection.
tau setup
Called automatically on first run if no providers are configured.
tau provider
Manage provider authentication from the CLI.
tau provider list # table of providers with status, source, and auth type
tau provider login [name] # authenticate an OAuth or API-key provider
tau provider login # interactive selector when stdin is a TTY
tau provider logout <name> # disable provider and clear managed credentials
Provider credentials are managed via the keychain or stored in ~/.config/tau/auth.yaml. See docs/providers.md for the full provider architecture.
tau models
List available models from the configured provider.
tau models [--json]
Uses the live models.dev catalog (network). For the model list used in the interactive TUI, see the embedded snapshot
(internal/providers/snapshot/).
tau refresh
Force a refresh of the models.dev network catalog and list models.
tau refresh
Downloads the latest catalog for the configured provider. This affects the tau models output and the snapshot
generator, but interactive sessions use the embedded offline snapshot (internal/providers/snapshot/models.json).
tau sessions
List saved chat sessions.
tau sessions
Shows a table of sessions with ID, model, message count, tokens, cost, and date. Use /session inside the TUI for
richer session management.
tau token
Print the resolved API key / bearer token for the selected provider.
tau token
Useful for debugging auth configuration.
tau update
Update the current tau binary from GitHub release assets, or check for available updates.
tau update [--check] [--version v0.16.2] [--repo owner/repo] [--force]
The updater downloads the platform archive and checksums.txt, verifies the archive checksum, extracts the tau binary,
and applies it in place.
By default, update checks only happen when you run tau update manually. Set
updates.mode: warn in configuration to keep manual
checks with update notifications, or updates.mode: disabled to disable all update
checks including tau update. Dev builds (version dev) are always excluded
from update checks — only release builds are eligible.
Configuration
Tau loads ~/.config/tau/config.yaml (global) and .tau.yaml (project-local). Example configs are in
config-example.yaml and config-deepseek-example.yaml.
Minimal configuration
# ~/.config/tau/config.yaml
default_provider: deepseek
default_model: deepseek-chat
providers:
- name: deepseek
base_url: https://api.deepseek.com/v1
auth:
type: api_key
api_key_env: DEEPSEEK_API_KEY
Model metadata (context window, pricing, reasoning) is loaded from the embedded snapshot - you do not need to repeat it
in config. See docs/ai-sdk.md for full integration details.
ProviderConfig fields
| Field | Description |
|---|---|
name |
Provider identifier (matches tau's catalog ID) |
base_url |
API endpoint. Must include /v1 when the provider uses it |
type |
ai-sdk class override (anthropic for Anthropic native API; omit for OpenAI-compatible) |
auth.type |
api_key, none, or oauth_pkce |
auth.api_key_env |
Environment variable name for the API key |
auth.api_key |
Literal API key (not recommended; prefer api_key_env) |
headers |
Optional static request headers; do not put bearer tokens here |
models |
Optional list of model overrides (see below) |
Model overrides
Tau's embedded snapshot provides model metadata. Override individual fields only when you need to customise them:
providers:
- name: openai
auth:
type: api_key
api_key_env: OPENAI_API_KEY
models:
- id: gpt-5.4
context_window: 200000
default_max_tokens: 16384
Documentation Index
Architecture & Design
- Architecture Overview - system design, communication patterns, layer map
- Event Bus Architecture - type-based event routing, publishers, subscribers
Core Systems
- Agent Coordinator - turn loop, command handlers, tool execution, prompts
- Chat Types - complete command/event reference, core types
- Tools - registry, built-in tools, mutation queue, UIBridge
- Commands - slash command registry, custom commands
UI Systems
- Terminal UI (TUI) - inline rendering, widget tree, slash commands, completions, notifications
- Web UI - Vue 3 SPA, state management, components, protocol, build
- Server & Bridge - HTTP/WebSocket server, event fan-out, wire format
- taui Framework - standalone TUI rendering engine, widgets, color system
Infrastructure
- Configuration - YAML config format, env vars, CLI flags
- Providers - provider catalogue, auth state, model discovery, dynamic switching
- AI SDK Integration - embedded snapshot, dynamic streamer, URL rules, reasoning
- Sessions - SQLite persistence, session lifecycle, JSONL export
- Skills - SKILL.md discovery, frontmatter parsing, prompt rendering
Extensibility
- Plugin SDK - gRPC extension system, tools, slash commands, lifecycle events