tau

A small, readable terminal coding agent — and a working example of how coding agents are built.

Documentation · Quickstart · Architecture · PyPI · Roadmap

What is Tau?

Tau is a coding agent that lives in your terminal. You type requests like "explain this repo", "add tests", or "fix this stack trace"; Tau can read files, edit code, run commands, and keep a durable session history while streaming what it is doing.

Tau is also meant to be read. It is a teaching project for understanding the shape of a coding-agent system without starting from a giant production codebase.

tau_coding  →  tau_agent  →  tau_ai

• tau_ai translates model providers into Tau's provider-neutral stream.
• tau_agent owns the portable brain: messages, tools, events, loop, harness, and session primitives.
• tau_coding wraps the brain as a real coding app: CLI, TUI, file/shell tools, provider config, project instructions, skills, and on-disk sessions.

The important boundary is:

AgentHarness = reusable brain
CodingSession = coding-agent environment
TUI = one possible frontend

The core does not know about Textual, Rich, local config paths, slash commands, or rendering. Frontends consume events.

Install

Tau is published on PyPI as tau-ai and installs a tau command. It requires Python 3.12 or newer. The recommended installers use uv and install it first when necessary.

macOS and Linux:

curl -LsSf https://twotimespi.dev/install.sh | sh

Windows PowerShell:

irm https://twotimespi.dev/install.ps1 | iex

The installers do not use sudo. They announce before installing uv, install Tau in an isolated tool environment, verify tau --version, and report if a shell restart is needed. You can inspect the shell installer or PowerShell installer before running it.

Already have a package manager? Install Tau directly:

uv tool install tau-ai
# or
pipx install tau-ai
# or
python -m pip install tau-ai

Then check it worked:

tau --version

Tau is also available on conda-forge, and can be installed using pixi:

pixi global install tau-ai

Upgrade a normal installation with:

tau update

For local development:

git clone https://github.com/huggingface/tau.git
cd tau
uv sync --dev
uv run tau --version

To make the checkout-backed command available globally, install it as an editable tool:

uv tool install --editable --force .

Run that command again after git pull. Editable installs expose source-code changes immediately, but the tool environment's package metadata, dependencies, and entry points are only refreshed when uv reinstalls the tool. Without the refresh, tau --version can still show the version from the previous install.

Quickstart

Run Tau from the project you want it to work on:

cd my-project
tau

Then type a request and press Enter:

explain what this project does

One-shot print mode is useful for scripts and quick prompts:

tau -p "summarize the architecture"
tau --cwd /path/to/project -p "find the CLI entry point"

Tau needs a model provider. Start Tau and connect one with /login:

tau

/login
/login openai
/login openai-codex
/model

Tau ships with support for OpenAI, Anthro