tau

module

v0.10.0 Latest Latest Go to latest Published: Aug 5, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/ihavespoons/tau

Links

Open Source Insights

README ¶

tau

A coding agent for your terminal. tau is a Go reimplementation of Pi — same architecture, same feature surface, same minimalist philosophy — shipped as a single static binary with no runtime dependencies.

Status: early development. tau is being built in phases toward parity with Pi v0.82.1. The interactive agent works on Anthropic models; other providers, session trees, and the extension subprocess protocol are still landing.

tau does not ask before it acts. It edits files and runs shell commands without a confirmation prompt. Run it on a clean git tree or in a scratch directory until approval gating lands.

Goals

Single binary. No Node, no npm. brew install or download one file.
Pi parity. The agent loop, session trees, providers, extensions, themes, skills, and modes you know from Pi, in idiomatic Go.
Easy migration. tau reads your existing ~/.pi state (sessions, settings, auth, models) and imports it. Existing Pi TypeScript extensions run against tau via a host shim.
Libraries first. ai, agent, session, tools, and extension are importable Go packages, not just internals of the CLI.

Install

brew install ihavespoons/tap/tau
# or
go install github.com/ihavespoons/tau/cmd/tau@latest

Use

tau login                  # Claude Pro/Max OAuth, or an API key with -k
tau                        # interactive session in the current directory
tau -c                     # …continuing the most recent one
tau -p "fix the failing test"    # one-shot, non-interactive
tau -p --mode json "…"     # JSONL events, for scripts and CI

Tools: read, write, edit, bash, grep, find, ls. Search runs on ripgrep and fd, found on your PATH or downloaded into ~/.tau/agent/bin on first use — set TAU_OFFLINE=1 to refuse the download instead.

Inside a session: Enter sends, Alt+Enter adds a newline, Esc stops the agent, Ctrl+P cycles models, Ctrl+T cycles thinking level, and /help lists the commands. Typing while the agent is working steers it — the message is delivered at the next turn boundary instead of starting a competing run.

The transcript is printed into your terminal's scrollback rather than an alternate screen, so scrolling, selection, and search keep working, and session length costs nothing to render.

Other providers

37 providers and 1,153 models ship compiled in — Anthropic, OpenAI, OpenRouter, Google, Groq, Cerebras, xAI, DeepSeek, Mistral, Together, Fireworks, Moonshot, Z.ai, MiniMax, NVIDIA, Bedrock, Vertex, Azure, Copilot, the Vercel and Cloudflare gateways, and the rest. Set the provider's API key environment variable and its models appear in tau models, ready to select.

The catalog is generated from models.dev and diffed field-by-field against Pi's own, so the per-model quirks come along with it: which thinking levels a model accepts, which token field it wants, where its pricing tier changes, whether it needs cache markers, which wire it actually speaks.

All ten wire APIs are live: Anthropic messages, OpenAI chat-completions, OpenAI responses, Azure OpenAI, Gemini, Vertex AI, Mistral, Bedrock ConverseStream, the ChatGPT Codex backend, and pi-messages — Pi's own protocol. Every provider in the catalog is reachable.

Seven providers have a login rather than a key, so a subscription you already pay for works without one:

tau login                    # Anthropic — Claude Pro/Max
tau login github-copilot     # device flow
tau login openai-codex       # ChatGPT subscription
tau login openrouter         # browser; yields a permanent API key
tau login xai                # device flow — SuperGrok or X Premium
tau login kimi-coding        # device flow
tau login radius             # browser or device code

Radius is a gateway rather than a vendor, and it publishes no fixed model list: which models you can reach is a property of your account. Logging in fetches the catalog and caches it in ~/.tau/agent/models-store.json, so it is there on the next start without a network round trip; logging in again refreshes it. Point tau at your own deployment with TAU_RADIUS_GATEWAY.

Two authenticate from the ambient cloud environment instead. Vertex uses Application Default Credentials, so gcloud auth application-default login is enough; set GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION. Bedrock uses the standard AWS chain — AWS_PROFILE, environment keys, SSO, or an instance role — and honours AWS_REGION, inference-profile ARNs, and AWS_BEARER_TOKEN_BEDROCK for Bedrock API keys. Everything else takes an API key from the environment.

Anything not listed that speaks /v1/chat/completions — vLLM, llama.cpp, LiteLLM, Ollama, a private gateway — can be declared in ~/.tau/agent/models.json and used immediately:

{
  "providers": {
    "openrouter": {
      "name": "OpenRouter",
      "baseUrl": "https://openrouter.ai/api/v1",
      // A "$VAR" reference is read from the environment, so the key
      // never sits in a file.
      "apiKey": "$OPENROUTER_API_KEY",
      "models": [
        {
          "id": "anthropic/claude-sonnet-4.5",
          "reasoning": true,
          "input": ["text", "image"],
          "contextWindow": 1000000,
          "maxTokens": 64000,
          "cost": { "input": 3.0, "output": 15.0, "cacheRead": 0.3, "cacheWrite": 3.75 }
        }
      ]
    }
  }
}

Then tau --model openrouter/anthropic/claude-sonnet-4.5, or set defaultModel in settings. Omitting api assumes openai-completions, which is what nearly every endpoint speaks; the per-provider quirks are detected from the provider id and base URL. Any of the ten wires can be named instead — "api": "pi-messages" reaches a backend speaking Pi's own protocol.

Qualify a model with its provider — anthropic/claude-sonnet-5, not claude-sonnet-5. A bare id is matched loosely across the whole catalog, and a dozen providers resell the same models.

To refresh the compiled catalogs after an upstream change: go run ./cmd/tau-genmodels -refresh.

MCP

tau speaks the Model Context Protocol through a bundled extension. Configure servers in ~/.tau/agent/mcp.json, using the same mcpServers shape other MCP hosts read:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    },
    "example": {
      "url": "https://example.com/mcp",
      "headers": { "Authorization": "Bearer …" }
    }
  }
}

A project may add servers in .tau/mcp.json, but only in a directory you have trusted — otherwise cloning a repository would be enough to make tau launch a process. Run /mcp to see what connected.

Everything MCP does goes through the public extension package, which is the point: it is the acceptance test for that API, not a privileged core feature.

License

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
agent Package agent is tau's agent runtime — the port of Pi's @earendil-works/pi-agent-core.	Package agent is tau's agent runtime — the port of Pi's @earendil-works/pi-agent-core.
env Package env is the capability abstraction tools execute against: a filesystem and a shell.	Package env is the capability abstraction tools execute against: a filesystem and a shell.
env/osenv Package osenv implements env.Env against the local operating system: the real filesystem and a real bash shell.	Package osenv implements env.Env against the local operating system: the real filesystem and a real bash shell.
ai Package ai is a unified multi-provider LLM API — the tau port of Pi's @earendil-works/pi-ai (snapshot v0.82.1).	Package ai is a unified multi-provider LLM API — the tau port of Pi's @earendil-works/pi-ai (snapshot v0.82.1).
api/anthropic Package anthropic implements the anthropic-messages wire API — the tau port of Pi's packages/ai/src/api/anthropic-messages.ts (snapshot v0.82.1), re-based from the @anthropic-ai/sdk onto net/http.	Package anthropic implements the anthropic-messages wire API — the tau port of Pi's packages/ai/src/api/anthropic-messages.ts (snapshot v0.82.1), re-based from the @anthropic-ai/sdk onto net/http.
api/apishared Package apishared holds the helpers every wire API needs: the message transform Pi applies before any provider-specific conversion, deferred-tool splitting, and unicode sanitization.	Package apishared holds the helpers every wire API needs: the message transform Pi applies before any provider-specific conversion, deferred-tool splitting, and unicode sanitization.
api/bedrock Package bedrock implements the bedrock-converse-stream wire API — the tau port of Pi's packages/ai/src/api/bedrock-converse-stream.ts (snapshot v0.82.1).	Package bedrock implements the bedrock-converse-stream wire API — the tau port of Pi's packages/ai/src/api/bedrock-converse-stream.ts (snapshot v0.82.1).
api/googlegenai Package googlegenai implements Gemini's generateContent wire.	Package googlegenai implements Gemini's generateContent wire.
api/mistralconv Package mistralconv implements Mistral's chat wire.	Package mistralconv implements Mistral's chat wire.
api/openaichat Package openaichat implements the openai-completions wire API — the /v1/chat/completions shape.	Package openaichat implements the openai-completions wire API — the /v1/chat/completions shape.
api/openairesp Package openairesp implements OpenAI's responses wire.	Package openairesp implements OpenAI's responses wire.
api/pimessages Package pimessages implements the pi-messages wire API: Pi's own protocol, spoken by the Radius gateway and by any backend that chooses to implement it (a models.json provider with "api": "pi-messages" reaches one).	Package pimessages implements the pi-messages wire API: Pi's own protocol, spoken by the Radius gateway and by any backend that chooses to implement it (a models.json provider with "api": "pi-messages" reaches one).
auth Package auth implements provider credential storage and auth resolution — the tau port of Pi's packages/ai/src/auth (snapshot v0.82.1) plus the file-backed store from coding-agent's auth-storage.ts.	Package auth implements provider credential storage and auth resolution — the tau port of Pi's packages/ai/src/auth (snapshot v0.82.1) plus the file-backed store from coding-agent's auth-storage.ts.
auth/oauth Package oauth implements the provider OAuth flows — the tau port of Pi's packages/ai/src/auth/oauth.	Package oauth implements the provider OAuth flows — the tau port of Pi's packages/ai/src/auth/oauth.
faux Package faux is a scripted in-memory provider — the backbone of tau's offline test suite (tau's analogue of Pi's providers/faux.ts).	Package faux is a scripted in-memory provider — the backbone of tau's offline test suite (tau's analogue of Pi's providers/faux.ts).
internal/sse Package sse decodes Server-Sent Event streams.	Package sse decodes Server-Sent Event streams.
partialjson Package partialjson salvages tool-call arguments from incomplete or malformed JSON produced during streaming.	Package partialjson salvages tool-call arguments from incomplete or malformed JSON produced during streaming.
provider Package provider assembles wire APIs and model catalogs into named providers — the tau analogue of pi-ai's providers/ + models.ts collection.	Package provider assembles wire APIs and model catalogs into named providers — the tau analogue of pi-ai's providers/ + models.ts collection.
provider/catalog Package catalog holds tau's compiled model data: what every known provider offers, generated from vendored upstream snapshots by cmd/tau-genmodels.	Package catalog holds tau's compiled model data: what every known provider offers, generated from vendored upstream snapshots by cmd/tau-genmodels.
cmd
tau command
tau-genmodels command Command tau-genmodels generates tau's compiled model catalogs.	Command tau-genmodels generates tau's compiled model catalogs.
coding Package coding wires the runtime pieces into a working coding agent: provider + agent loop + tools + session persistence.	Package coding wires the runtime pieces into a working coding agent: provider + agent loop + tools + session persistence.
config Package config resolves tau's on-disk locations.	Package config resolves tau's on-disk locations.
extension Package extension is tau's in-process extension API — the Go port of Pi's ExtensionAPI.	Package extension is tau's in-process extension API — the Go port of Pi's ExtensionAPI.
extensions
mcp Package mcp is tau's bundled Model Context Protocol client, shipped as an extension rather than as a core feature.	Package mcp is tau's bundled Model Context Protocol client, shipped as an extension rather than as a core feature.
frontmatter Package frontmatter parses YAML frontmatter from markdown files, shared by skills and prompt templates.	Package frontmatter parses YAML frontmatter from markdown files, shared by skills and prompt templates.
internal
tui Package tui is tau's interactive terminal interface, built on Bubble Tea.	Package tui is tau's interactive terminal interface, built on Bubble Tea.
models Package models is tau's runtime model registry: the compiled provider catalog layered with user-supplied models.json (custom providers, extra models, and overrides of built-ins), plus Pi's model-reference grammar.	Package models is tau's runtime model registry: the compiled provider catalog layered with user-supplied models.json (custom providers, extra models, and overrides of built-ins), plus Pi's model-reference grammar.
prompt Package prompt builds tau's system prompt and discovers the project context files that feed it.	Package prompt builds tau's system prompt and discovers the project context files that feed it.
prompttemplate Package prompttemplate loads and expands markdown prompt templates.	Package prompttemplate loads and expands markdown prompt templates.
session Package session implements tau's session store: an append-only JSONL tree (format version 3) that is byte-compatible with Pi's, so sessions written by either agent can be read by the other.	Package session implements tau's session store: an append-only JSONL tree (format version 3) that is byte-compatible with Pi's, so sessions written by either agent can be read by the other.
settings Package settings is tau's two-scope configuration layer — the port of Pi's settings-manager.ts.	Package settings is tau's two-scope configuration layer — the port of Pi's settings-manager.ts.
skills Package skills discovers and parses Agent Skills (SKILL.md files) and renders them for the system prompt.	Package skills discovers and parses Agent Skills (SKILL.md files) and renders them for the system prompt.
slashcmd Package slashcmd is tau's slash-command engine: parsing, a registry, and the built-in command set.	Package slashcmd is tau's slash-command engine: parsing, a registry, and the built-in command set.
tools Package tools implements tau's built-in agent tools, ported from Pi's coding-agent tool set.	Package tools implements tau's built-in agent tools, ported from Pi's coding-agent tool set.
trust Package trust gates project-local configuration — the port of Pi's trust-manager.ts and project-trust.ts.	Package trust gates project-local configuration — the port of Pi's trust-manager.ts and project-trust.ts.