Retrieved article excerpt
Open article · Retrieved 2026-09-14T17:24:45.365907+00:00
[Tau — a Python coding-agent harness inspired by Pi](https://github.com/huggingface/tau/blob/main/docs/assets/tau-header.svg)
**A small, readable terminal coding agent — and a working example of how coding agents are built.**
[Documentation](https://twotimespi.dev/)
·
[Quickstart](https://twotimespi.dev/quickstart/)
·
[Architecture](https://twotimespi.dev/internals/architecture/)
·
[PyPI](https://pypi.org/project/tau-ai/)
·
[Roadmap](https://github.com/huggingface/tau/issues/1)
**[Join the Tau Discord community →](https://link.alejandro-ao.com/tau-discord)**
---
## 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`](https://docs.astral.sh/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](https://twotimespi.dev/install.sh)
or [PowerShell installer](https://twotimespi.dev/install.ps1) 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](https://conda-forge.org), and can be installed using [pixi](https://pixi.prefix.dev/latest/#installation):
```
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, Anthropic, OpenAI Codex subscription auth,
OpenRouter, Hugging Face, and custom OpenAI-compatible endpoints, including local
models. See the [providers guide](https://twotimespi.dev/guides/providers-and-models/).
The built-in catalog lives in `src/tau_coding/data/catalog.toml`; add your own
providers and models by dropping a `~/.tau/catalog.toml` with the same schema —
no code changes required.
## What Tau can do
- Interactive Textual TUI and non-interactive print mode.
- Built-in coding tools: `read`, `write`, `edit`, and `bash`.
- Durable JSONL sessions under `~/.tau/sessions/` with resume and branching.
- Slash commands for login, model selection, sessions, compaction, export, theme,
and more.
- Project instructions from `AGENTS.md`, `.tau/`, and `.agents/` resources.
- User skills, prompt templates, and custom TUI themes.
- Context accounting, manual compaction, and optional automatic compaction.
- Provider-neutral event rendering for Rich, plain text, JSON, transcripts, and
custom frontends.
## Philosophy
Tau follows a few rules:
- **Small layers beat magic.** Each package has one job and can be read alone.
- **Events are the contract.** Providers, renderers, the TUI, and custom
frontends meet at a typed event stream.
- **The core stays portable.** The reusable harness does not depend on the CLI,
Textual, Rich, or Tau's file layout.
- **Tools are ordinary typed functions.** A tool is a schema plus an async
executor returning a structured result.
- **Sessions are durable and inspectable.** History is append-only JSONL; active
context can be compacted without rewriting the record.
- **Documentation follows implementation.** The public docs explain the result;
`dev-notes/` preserves the phase-by-phase build journal.
## Use Tau as a library
```
from tau_agent import AgentHarness, AgentHarnessConfig
harness = AgentHarness(
AgentHarnessConfig(
provider=provider,
model="my-model",
system="You are a helpful coding agent.",
tools=tools,
)
)
async for event in harness.prompt("Explain this package"):
print(event)
```
Because the harness emits events instead of rendering UI directly, the same core
can drive the built-in TUI, print mode, or a frontend you build yourself.
## Development
See [CONTRIBUTING.md](https://github.com/huggingface/tau/blob/main/CONTRIBUTING.md) for project philosophy, layer boundaries, testing expectations, and pull request guidelines.
```
uv sync --dev
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run mypy
```
Run Tau from the checkout:
```
uv run tau
uv run tau -p "explain this repo"
```
Run the Hugo documentation site:
```
cd website
hugo server -D
```
Open <http://localhost:1313/>. Build with `hugo --minify`.
## Documentation
User docs are published at <https://twotimespi.dev/> and live in
`website/content/`.
Useful entry points:
- [What is Tau?](https://twotimespi.dev/what-is-tau/)
- [Quickstart](https://twotimespi.dev/quickstart/)
- [Core concepts](https://twotimespi.dev/concepts/)
- [Architecture overview](https://twotimespi.dev/internals/architecture/)
- [The agent loop & events](https://twotimespi.dev/internals/agent-loop/)
- [CLI reference](https://twotimespi.dev/reference/cli/)
Tau is under active development. The implementation roadmap is tracked in
[GitHub issue #1](https://github.com/huggingface/tau/issues/1).
## License
Tau is released under the [MIT License](https://github.com/huggingface/tau/blob/main/LICENSE).