sam c66c0a2a38 refactor(config): move loading into infrastructure/configuration
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.
2026-07-29 11:07:41 +10:00
2026-07-28 18:46:50 +10:00
2026-07-29 02:10:44 +10:00
2026-07-28 18:46:50 +10:00
2026-07-28 18:46:50 +10:00
2026-07-28 18:46:50 +10:00
2026-07-28 18:46:50 +10:00
2026-07-28 18:46:50 +10:00

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:

  1. 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.

  2. tau provider CLI:

    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 credentials
    

    For non-OAuth providers, tau provider login stores a managed API key in auth.yaml.

  3. Environment variable: Export the provider's API key env var (e.g. DEEPSEEK_API_KEY=sk-...). Tau detects it at startup.

  4. TUI slash commands: /provider [name] to toggle a provider, /provider login <name> for OAuth flow.

  5. 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

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
S
Description
Archie connects events from your systems to agents that can investigate, reason, and act. Define what an event means, map its data into a workflow, and give that workflow an agent equipped for the job: its own execution environment, tools, and identity.
https://archie.catlow.cloud
Readme Apache-2.0
133 MiB
0 Stars 1 Watchers 0 Forks
2026-11-10 10:01:23 +00:00
Languages
Go 76.8%
Vue 13.1%
TypeScript 7.8%
JavaScript 1.2%
Shell 0.6%
Other 0.4%