# HuggingFace/tau: A Python port of Pi's minimalist coding agent

> Source: <https://github.com/huggingface/tau>
> Published: 2026-09-14 16:37:17+00:00

**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)

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

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.

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.

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

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.

``` python
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.

See [CONTRIBUTING.md](/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/](http://localhost:1313/). Build with `hugo --minify`.

User docs are published at [https://twotimespi.dev/](https://twotimespi.dev/) and live in
`website/content/`.

Useful entry points:

Tau is under active development. The implementation roadmap is tracked in
[GitHub issue #1](https://github.com/huggingface/tau/issues/1).

Tau is released under the [MIT License](/huggingface/tau/blob/main/LICENSE).