Configuration & files

Where Tau stores state, and the shape of its config files.

Tau keeps durable state in your home directory (~/.tau/) and reads project-local resources from your working directory. This page is a reference for those locations and file formats.

Tau home

Tau stores user-level configuration and state in ~/.tau/ by default. Set TAU_HOME to select a different home for one invocation or shell profile:

TAU_HOME="$HOME/.tau-personal" tau

A non-empty override must be an absolute path after optional ~ expansion. An unset or empty value keeps the ~/.tau default. Tau does not interpolate variables inside the value, so let your shell expand $HOME as in the example. Symlink paths are preserved rather than resolved.

Every Tau-owned user path shown as ~/.tau/... in this documentation follows TAU_HOME, including credentials, sessions, provider preferences, settings, trust decisions, extensions, logs, local-backend state, and model/update caches. The override does not relocate ~/.agents, project-level .tau/.agents resources, explicit extension paths, or credentials supplied through environment variables. It is an application-profile boundary, not a security sandbox. Embedding applications that supply an explicit TauPaths keep using those paths regardless of the environment.

For profiles containing OAuth credentials, create the directories with private permissions before signing in:

# POSIX shells
install -d -m 700 "$HOME/.tau-personal" "$HOME/.tau-work"

On Windows, create the directories first and use the platform’s access-control tools if other local users can read your profile. PowerShell can select a home for the current process with $env:TAU_HOME = "$HOME\.tau-personal" before launching tau.

<tau-home>/              # ~/.tau unless TAU_HOME is set
├── catalog.toml        # optional provider/model catalog overlay
├── providers.json      # provider/model preferences
├── models-store.json   # refreshed models.dev catalog cache
├── codex-models-store.json # account-scoped Codex model snapshot
├── credentials.json    # saved API keys / OAuth tokens (0600, atomic writes)
├── state/extensions/    # built-in integration state, including llama.cpp
├── settings.json       # general settings (trust default, shell prefix)
├── trust.json          # versioned project-input trust decisions
├── tui.json            # TUI theme, keybindings, and layout
├── sessions/           # saved sessions, per project
├── skills/             # user-level skills
├── prompts/            # user-level prompt templates
├── themes/             # user-level TUI themes
├── SYSTEM.md           # optional replacement system-prompt base
├── APPEND_SYSTEM.md    # optional appended system-prompt instructions
├── AGENTS.md           # global project instructions
└── logs/               # diagnostics

Tau also reads user-level .agents resources: ~/.agents/skills/, ~/.agents/prompts/, ~/.agents/AGENTS.md.

settings.json may contain "defaultProjectTrust": "ask" | "always" | "never". It is user-global only; a project cannot choose its own trust policy. The default is ask. Interactive ask opens the trust modal; headless ask safely declines. trust.json is managed atomically by Tau; do not add relative paths or unknown fields. See Project trust.

Startup update checks cache their latest PyPI result in ~/.tau/cache/update-check.json and refresh at most once per day. A failed check (for example while offline) is retried after an hour. Set TAU_NO_UPDATE_CHECK=1 to disable the check; Tau also skips it when CI is set.

models-store.json caches an ETag-revalidated models.dev catalog newer than the bundled snapshot. /model refreshes it in the background at most every four hours; tau update --models forces revalidation. Set TAU_OFFLINE=1 to disable catalog network access. User catalog.toml overrides still apply after the cache.

codex-models-store.json contains only parsed model metadata and the active Codex account ID. Tau loads it at startup, then refreshes it when /model or /scoped-models opens; a snapshot from a different account is ignored. It never contains OAuth tokens.

System prompt files

Tau can replace or extend its generated system prompt with Tau-native Markdown files:

~/.tau/SYSTEM.md                 # user replacement
~/.tau/APPEND_SYSTEM.md          # user append
<project>/.tau/SYSTEM.md         # project replacement
<project>/.tau/APPEND_SYSTEM.md  # project append

Replacement inputs use precedence: explicit CLI input, then the project SYSTEM.md, then the user SYSTEM.md. Append inputs compose instead of shadowing one another: Tau adds the user APPEND_SYSTEM.md, then the project APPEND_SYSTEM.md, then every explicit --append-system-prompt value in CLI order. Replacement content still receives all append text, project instructions, eligible skills, the current date, and the working directory. Empty files are valid contributions.

Run /reload after adding, changing, or removing a file. Tau rebuilds the prompt for the next model request without adding it to session history. /session resource diagnostics identify selected append files and selected, shadowed, or CLI-overridden replacement files. A selected file that cannot be inspected or decoded as UTF-8 stops startup or reload rather than silently falling back.

System prompt files are Tau-specific and are not discovered from .agents. Project files load only after the destination cwd is trusted. User files and explicit CLI values remain available when project inputs are declined. Trust is an input-loading guard, not a sandbox; inspect trusted prompt files because they can replace or extend the model’s highest-priority instructions.

Network proxies

Tau uses httpx for provider requests, OAuth token refreshes, and startup update checks, so it honors standard proxy environment variables such as HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, and NO_PROXY.

SOCKS proxies are supported by the base installation. Use explicit schemes when you can:

export ALL_PROXY=socks5://127.0.0.1:1080
# or, when proxy-side DNS resolution is required:
export ALL_PROXY=socks5h://127.0.0.1:1080

Tau also accepts the generic socks:// form that some systems and tools set in the environment. Before creating its own HTTP clients, Tau normalizes socks://... to socks5://... because httpx does not recognize the generic scheme directly.

This matters for users behind corporate proxies, VPNs, local tunnels, or privacy/network-routing setups: without SOCKS support and normalization, Tau can fail before making a model API request with an error like Unknown scheme for proxy URL URL('socks://...').

Providers

Tau separates provider metadata from runtime preferences:

  • src/tau_coding/data/catalog.toml ships the built-in provider/model catalog.
  • ~/.tau/catalog.toml optionally adds personal providers or overlays built-ins.
  • ~/.tau/providers.json stores runtime preferences such as the default provider, default model, scoped models, headers, and timeout/retry settings. Tau updates the default model automatically when a committed interactive /model selection finishes its preview at the next message.

The built-in llama.cpp backend stores only its normalized endpoint and safe server-reported model snapshot at ~/.tau/state/extensions/llama.cpp.json. Optional credentials remain in credentials.json or LLAMA_API_KEY; dynamic llama.cpp provider definitions are not written to catalog.toml or providers.json. Scoped llama.cpp entries in providers.json contain only the stable llama.cpp provider ID and exact model ID; stale entries do not create availability or router work. For Hugging Face GGUF search, Tau reads HF_TOKEN or standard Hugging Face token files but never stores or forwards that token to the llama.cpp server. The independent server needs its own HF_TOKEN for gated downloads. See the local inference guide.

Tau intentionally reads catalog overlays only from the user-level ~/.tau/catalog.toml. There is no project-level .tau/catalog.toml, so cloning a repository cannot silently redirect a provider’s base_url or credentials to an unexpected service.

Provider catalog overlays

Add reusable custom provider definitions to ~/.tau/catalog.toml:

schema_version = 1

[[providers]]
name = "local-gateway"
display_name = "Local Gateway"
kind = "openai-compatible"
base_url = "http://localhost:11434/v1"
api_key_env = "LOCAL_GATEWAY_API_KEY"
credential_name = "local-gateway"
models = ["qwen-coder"]
default_model = "qwen-coder"
docs_url = "https://example.test/local-gateway"

[providers.context_windows]
qwen-coder = 64000

Catalog entries support kind values of openai-compatible, anthropic, and openai-codex. For most custom services, start with openai-compatible.

User catalog overlays can be partial when they use the same name as a built-in provider. Scalar fields replace built-in values, models are merged with user models first, and context_windows are merged. Provider-level compat is merged key by key. Model metadata is merged by model; its headers, compat, and thinking_level_map mappings are merged, while other metadata fields—including the complete cost_tiers array—replace the built-in value. A model’s compat wins over the provider’s, so a built-in per-model value overrides a provider-level overlay — override at the model level to change it.

removed_models is an additive provider-scoped tombstone list. Tau applies it last and removes matching model-list, metadata, context-window, thinking, and default references after merging. Bundled tombstones therefore prevent stale user overlays from restoring models that Tau previously advertised for the wrong provider. They do not affect the same model ID on another provider.

OpenAI prompt-cache compat keys

Tau enables OpenAI cache affinity automatically only for api.openai.com and the dedicated Codex OAuth provider. OpenAI-compatible gateways can opt in per provider or model:

KeyEffect
supportsPromptCacheKeySends the stable session-derived prompt_cache_key body field
sendSessionAffinityHeadersSends headers using sessionAffinityFormat
sessionAffinityFormatopenai sends session_id; openrouter sends x-session-id

Unknown gateways retain their existing request shape by default. Enable only fields documented by the target service. Codex uses its dedicated session-id header mapping and does not read these OpenAI-compatible settings.

Anthropic prompt-cache compat keys

Providers using the anthropic-messages API accept three compat booleans controlling prompt caching. All default to enabled, except that cache_control is detected as unsupported for any base URL that is not api.anthropic.com, since several providers speak the Anthropic protocol through a gateway.

KeyEffect when false
supportsCacheControlNo cache breakpoints at all; the request is byte-identical to an uncached one
supportsLongCacheRetentionClamps the 1 hour TTL to the 5 minute default
supportsCacheControlOnToolsDrops only the tool-schema breakpoint

Set them per provider or per model. For example, to stop requesting the one-hour cache on a Claude subscription:

schema_version = 1
[[providers]]
name = "anthropic"
compat = { supportsLongCacheRetention = false }

The thinking fields (thinking_levels, thinking_models, thinking_default, thinking_parameter) replace as a group when thinking_levels is present.

catalog.toml does not store runtime request options such as custom HTTP headers, timeouts, or retry settings. Put those in ~/.tau/providers.json on the matching provider entry.

Invalid catalog files fail loudly. Tau rejects unknown keys, empty required strings, empty model names, unsupported provider kinds, default models that are not listed in models, thinking_models or context_windows entries for unknown models, and non-positive or non-integer context-window values.

Model metadata can retain a backward-compatible flat cost and optionally provide ordered cost_tiers for rates that depend on input size:

[providers.model_metadata."long-context-model"]
cost = { input = 0.3, output = 1.2, cacheRead = 0.06, cacheWrite = 0 }
cost_tiers = [
  { max_input_tokens = 512000, input = 0.3, output = 1.2, cacheRead = 0.06, cacheWrite = 0 },
  { input = 0.6, output = 2.4, cacheRead = 0.12, cacheWrite = 0 },
]

Limits are inclusive, must increase strictly, and the final tier must omit max_input_tokens so every valid input size has a rate. Callers that understand tiers should select the first tier whose limit includes the input-token count; older callers continue to see cost as the base rate.

All rates are per million tokens. cacheWrite is the 5-minute cache-write rate; entries may add an optional cacheWrite1h rate for Anthropic’s 1-hour TTL cache writes, which Anthropic bills higher. When cacheWrite1h is absent, 1-hour writes fall back to the cacheWrite rate.

Provider preferences

Provider preferences live in ~/.tau/providers.json:

{
  "schema_version": 2,
  "default_provider": "local-gateway",
  "provider_preferences": {
    "local-gateway": {
      "default_model": "qwen-coder",
      "headers": { "X-Provider-Header": "value" },
      "thinking_defaults": { "qwen-coder": "low" },
      "timeout_seconds": 120,
      "max_retries": 2,
      "max_retry_delay_seconds": 0.5
    }
  },
  "scoped_models": [
    { "provider": "local-gateway", "model": "qwen-coder" }
  ]
}
  • provider_preferences keys must refer to providers from the effective catalog (src/tau_coding/data/catalog.toml plus ~/.tau/catalog.toml).
  • headers is optional (string→string). For example, Hugging Face organization billing can be configured with "headers": { "X-HF-Bill-To": "my-org" } on the huggingface provider preference. thinking_defaults remembers the preferred thinking level per model for new sessions; resumed sessions still use their session history. The built-in huggingface preference also accepts "inference_providers": { "zai-org/GLM-5.2": "deepinfra" }. Each key must be a configured model and each value an explicit provider suffix advertised by Hugging Face—not the fastest, cheapest, or preferred routing policies. Tau snapshots the selected suffix into new session metadata as a fixed route, retains it on resume, and sends only the suffixed wire model; ordinary model identity and catalog metadata remain unsuffixed. Without a preference, Tau starts in automatic mode and records the x-inference-provider reported by the first successful response as a sticky but recoverable route. After a retryable pre-output HTTP failure exhausts provider-level retries, Tau clears that automatic pin, retries the interrupted turn once through Hugging Face automatic routing, and stores the successful replacement. Explicitly configured routes never fail over. /session reports both mode and current route; changing the active session route is available through the external tau-huggingface extension; clone it and launch Tau with tau -e ./tau-huggingface, then use /hf route. timeout_seconds defaults to 60 (> 0); max_retries defaults to 2; max_retry_delay_seconds defaults to 1 (both ≥ 0). Retries cover transient HTTP statuses (408, 409, 425, 429, 5xx), transport errors, and transient in-stream SSE errors that arrive on an otherwise successful HTTP 200 response. Anthropic retries api_error, overloaded_error, and rate_limit_error; OpenAI Codex retries transient events such as server_is_overloaded. In-stream errors remain terminal after partial content to prevent duplicate output or tool calls. Existing session records that contain a Hugging Face route but predate route-mode metadata are treated as fixed, preventing an upgrade from overriding a potentially explicit user selection.
  • API keys and OAuth credentials are not stored here — they live in ~/.tau/credentials.json (private but not encrypted). OAuth objects may contain provider metadata such as a GitHub Enterprise domain and are refreshed automatically. Resolution order: stored credential, then the env var named by api_key_env.
  • The selected model must be present in that provider’s models list. Add custom or local model names to models before using them as defaults, CLI/TUI selections, or scoped models.
  • scoped_models are favorites for the Ctrl+P / Shift+Ctrl+P forward / backward quick-cycle.
  • providers.json uses schema_version: 2 and stores preferences only. Provider capabilities—model lists, context windows, transports, metadata, and thinking support—always come from the current effective catalog.
  • Older providers.json files that contain full providers entries are migrated automatically on first load. Tau keeps the original as providers.json.bak, moves custom provider definitions to ~/.tau/catalog.toml, and rewrites built-in providers from the current catalog while preserving safe preferences. This prevents old model or thinking metadata from hiding capabilities added by a Tau upgrade.
  • Tau ignores unrecognized preference fields for cross-version compatibility, but rejects an unsupported schema_version rather than risking a destructive rewrite with the wrong format.
  • Custom models declare thinking support in catalog.toml with thinking_levels, thinking_default, thinking_models, and thinking_parameter ("reasoning_effort", "reasoning.effort", or "anthropic.thinking").

Writes after /login, /model, or scoped-model changes reload the file first, apply only the requested change, write atomically, and keep a .bak backup.

See the Providers & models guide for usage.

Shell settings

Tau runs shell commands in a non-interactive shell — both terminal-input commands (! gst, !! ll) and the agent’s bash tool. Non-interactive shells don’t load your aliases from ~/.zshrc or ~/.bashrc, and Tau deliberately never reads those files (they can hold tokens and side effects).

To make your own aliases available, opt in with a shellCommandPrefix in ~/.tau/settings.json that loads a small Tau-specific alias file:

# ~/.tau/shell-aliases.bash
alias gst='git status'
alias ga='git add'
alias gc='git commit'
{
  "shellCommandPrefix": "shopt -s expand_aliases\nsource ~/.tau/shell-aliases.bash"
}

Then start a new session and try ! gst. Notes:

  • Commands run through bash-style non-interactive execution, so keep aliases POSIX/bash-compatible (zsh-only syntax, functions, or interactive startup logic may not work).
  • Changing settings.json affects new sessions; an already-running session keeps the prefix it started with.
  • The snake_case key shell_command_prefix is also accepted.
  • Unrecognized fields are ignored for compatibility with newer Tau versions; recognized fields remain strictly validated.

TUI settings

The built-in frontend reads optional settings from ~/.tau/tui.json:

{
  "theme": "high-contrast",
  "sidebar_position": "right",
  "turn_notification": "desktop",
  "keybindings": {
    "cancel": "escape",
    "command_palette": "ctrl+k",
    "session_picker": "ctrl+r",
    "queue_follow_up": "alt+enter",
    "insert_newline": "shift+enter",
    "accept_completion": "tab",
    "completion_next": "down",
    "completion_previous": "up",
    "thinking_cycle": "shift+tab",
    "model_cycle": "ctrl+p",
    "model_cycle_reverse": "ctrl+shift+p",
    "toggle_thinking": "ctrl+t",
    "toggle_tool_results": "ctrl+o",
    "copy_message": "ctrl+c",
    "quit": "ctrl+d"
  }
}

Built-in themes: tau-dark (default), tau-light, high-contrast. Custom themes are JSON files in ~/.tau/themes/ or a project’s .tau/themes/ — see Themes. Set one with /theme. Textual’s native theme picker is mapped to the same Tau themes and persists the same theme setting. A configured theme that cannot be found falls back to tau-dark with a startup notice, without overwriting the setting. Keys use Textual syntax; omitted keys keep their defaults. Tau ignores unrecognized settings and keybinding names so a tui.json written by a newer Tau version does not prevent an older version from starting. Recognized settings remain strict: Tau rejects invalid values, empty keys, and duplicate assignments.

  • sidebar_position: "right" (default), "left", or "off". Controls placement of the session metadata sidebar. "off" hides the sidebar entirely; the compact session info row below the prompt still works. In a running TUI, /sidebar temporarily toggles visibility without writing this setting; a temporarily shown "off" sidebar uses the default right position and the saved setting is honored again after restart.
  • turn_notification: "desktop" (default), "bell", or "off". When Tau’s terminal surface is unfocused and the agent becomes fully idle, "desktop" selects OSC 9 for Ghostty, iTerm2, and MinTTY, or Kitty’s OSC 99 protocol for Kitty. Unknown terminals receive no sequence rather than an incompatible one. "bell" explicitly emits the standard terminal bell so the terminal can mark the tab or request attention instead; depending on terminal settings, BEL may play a sound. Desktop notifications can also use the operating system’s configured notification sound. No notification is emitted while Tau has focus.

Full list in Keyboard shortcuts.

Sessions

~/.tau/sessions/<cleaned-path>-<short-hash>/

Each working directory gets its own subdirectory; transcripts are append-only JSONL preserving messages and state changes. The last non-legacy-leaf entry in file order is the active session-tree tip; historical leaf records remain readable but are ignored. Per-entry bookmarks are append-only label changes with target_id and an optional label; the latest change per target wins and null/empty clears it. Session display names remain session_info.title. Metadata is indexed per project. See the Sessions guide.

Skills, prompts & project context

Resource discovery order (later overrides earlier) is documented in Skills & prompt templates and Project instructions. In short: user-level ~/.tau and ~/.agents, then project-level .tau and .agents, with AGENTS.md discovered from the project root down to your current directory.

Context

/session reports a rough context estimate and breakdown. Auto-compaction triggers near the model’s context window minus a reserve; override per run with --auto-compact-threshold. Details in Managing context.