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/
├── catalog.toml        # optional provider/model catalog overlay
├── providers.json      # provider/model preferences
├── credentials.json    # saved API keys / OAuth tokens (0600, atomic writes)
├── 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. Set TAU_NO_UPDATE_CHECK=1 to disable the check; Tau also skips it when CI is set.

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

For each kind, precedence is explicit CLI input, then the project file, then the user file. A higher-precedence append file replaces the lower-precedence append file; Tau does not concatenate project and user files. Replacement content still receives the selected append text, project instructions, eligible skills, the current date, and the working directory. Empty files are valid explicit values.

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, shadowed, or CLI-overridden 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:

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" }
  ]
}

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:

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",
    "accept_completion": "tab",
    "completion_next": "down",
    "completion_previous": "up",
    "thinking_cycle": "shift+tab",
    "model_cycle": "ctrl+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.

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, model changes, and the active leaf of the session tree. 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.

Edit this page on GitHub ↗