huggingface/tau: a small Python coding agent you can actually read

The problem Tau solves: a coding agent you can read in one sitting

Most terminal coding agents arrive as large production codebases. You can use them, but you cannot follow what happens between your prompt and the file edit. Tau takes the opposite position. The README describes it as "a small, readable terminal coding agent", and adds that it is a working example of how coding agents are built. That second clause is the real product. The repository is organised so each package can be read alone, and the project keeps a dev-notes/ directory as a phase-by-phase build journal, which is unusual for a tool that also ships releases.

The intended reader is a Python developer who wants to understand the shape of an agent loop, or who wants a working CLI they can modify without archaeology. It is not aimed at teams that want a batteries-included assistant with a large plugin market. The scope is deliberately narrow: read, write, edit, bash, sessions, providers.

Tau is a port of Pi, a minimalist coding agent, and the Hugging Face organisation publishes it under MIT. The last push to main was on 2026-09-16, and the most recent tagged release in the repository is v0.4.4 on 2026-09-13.

Three layers, one event stream: how tau_ai, tau_agent and tau_coding fit together

The architecture is stated as a chain in the README:

tau_coding  →  tau_agent  →  tau_ai

tau_ai translates model providers into a provider-neutral stream. tau_agent owns what the README calls "the portable brain": messages, tools, events, the loop, the harness, and session primitives. tau_coding wraps that brain as a real application, adding the CLI, the Textual TUI, file and shell tools, provider configuration, project instructions, skills, and on-disk sessions.

The boundary the project cares about most is between AgentHarness and CodingSession. AgentHarness is the reusable brain. CodingSession is the coding-agent environment. The TUI is described as "one possible frontend". The core does not know about Textual, Rich, local config paths, slash commands, or rendering. Frontends consume events, and events are the contract.

That constraint has a visible consequence. Because the harness emits typed events rather than drawing to a terminal, the same core can drive the built-in TUI, print mode, or a frontend you write yourself. Tools follow the same discipline: the README calls a tool "a schema plus an async executor returning a structured result", which is why the tool surface stays small and typed instead of growing a plugin protocol.

Sessions are the other half of the design. History is append-only JSONL under ~/.tau/sessions/, with resume and branching. Active context can be compacted without rewriting the record, so the durable log and the working context are separate concerns.

Installing Tau and running a first prompt

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

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

On Windows PowerShell the equivalent is:

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

The README states that the installers do not use sudo, announce before installing uv, install Tau in an isolated tool environment, verify tau --version, and report if a shell restart is needed. Both scripts are linked from the README so you can read them before running them.

If you already have a package manager, install directly. Any of these three works:

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

Then confirm the command is on your path:

tau --version

Tau is also on conda-forge and can be installed with pixi global install tau-ai. Upgrades for a normal installation go through tau update.

For a first real use, change into the project you want Tau to work on and start it with no arguments:

cd my-project
tau

Type a request and press Enter. The README's example is "explain what this project does". Tau needs a model provider before it can answer, and you connect one from inside the session with /login. The README shows /login, /login openai, /login openai-codex and /model. Built-in support covers OpenAI, Anthropic, OpenAI Codex subscription auth, OpenRouter, Hugging Face, and custom OpenAI-compatible endpoints including local models.

For scripts, print mode skips the TUI:

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

If you are working from a checkout rather than an installed tool, the development path is git clone, cd tau, uv sync --dev, then uv run tau --version. The README notes a real gotcha with editable installs: uv tool install --editable --force . must be re-run after git pull, because source changes are picked up immediately but package metadata, dependencies and entry points only refresh on reinstall. Without that refresh, tau --version can keep reporting the previous version.

Custom providers and project instructions without touching the source

The built-in model catalog lives at src/tau_coding/data/catalog.toml. The README states that you can add providers and models by dropping a ~/.tau/catalog.toml with the same schema, and that this requires no code changes. That is the practical extension point for anyone pointing Tau at a self-hosted OpenAI-compatible endpoint.

Project behaviour is configured through AGENTS.md, .tau/ and .agents/ resources. The README also lists user skills, prompt templates and custom TUI themes as supported resources, and slash commands for login, model selection, sessions, compaction, export and theme. Context accounting is exposed, with manual compaction and optional automatic compaction.

One design choice worth noting: because the core is kept free of local config paths, anything file-layout-specific lives in tau_coding. That keeps the harness portable, but it also means extension behaviour is tied to the coding layer rather than the brain. If you are building a non-coding frontend, you inherit the event stream and the harness, not the catalog and project-instruction machinery.

Where Tau is the wrong tool

The most concrete limitation is the Python floor. pyproject.toml sets requires-python = ">=3.12", so anyone on 3.11 or older cannot install it without changing environments. The dependency list is short but not trivial: anyio, httpx with SOCKS support, packaging, pillow, pydantic, pygments, rich, textual, typer. Textual is pinned at >=8.2.8, and a major-version bump there would land on Tau's TUI directly.

There is no provider bundled in the box. A fresh install cannot answer a prompt until you run /login or configure a custom endpoint. That is a deliberate separation, but it means the first-run experience depends on credentials you supply.

The library surface is also not a stability promise. The README shows AgentHarness and AgentHarnessConfig being constructed and iterated with async for, and calls the core portable, but it does not document a versioning policy for those classes. A project at v0.4.4 with releases days apart is moving. If you build on the harness, expect to track changes.

Finally, the README does not document a rollback or downgrade procedure for a bad upgrade, and it does not describe a plugin system. If your requirement is a stable extension API with third-party packages, this is not that. The extension model here is reading and editing the source.

Tau as a library, and how it differs from a general-purpose agent framework

The clearest alternative in the same space is a general-purpose agent framework such as LangChain or LangGraph, where the unit of composition is a chain or a graph of nodes and the framework supplies integrations. Tau inverts that. The unit of composition is a typed event stream from a harness, and the framework supplies almost nothing beyond the loop, the tools and the session log.

The README's library example makes the difference concrete:

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)

You supply the provider and the tools. In exchange you get an async iterator of events you can render however you like, plus session primitives and a coding layer that already implements read, write, edit and bash. A graph framework gives you more orchestration primitives and a much larger surface to learn. Tau gives you fewer primitives and a codebase you can finish reading.

If you want a coding agent rather than an agent framework, the honest comparison is against established terminal agents. Tau's differentiator is not capability breadth. It is that the whole system is three packages, MIT licensed, with a build journal in dev-notes/ and documentation that the README says follows implementation.

Maintenance, licence and the cost of upgrading

Tau is not archived, and the last push was on 2026-09-16, one day before this writing. The release cadence in the repository is tight: v0.4.2 on 2026-09-10, v0.4.3 on 2026-09-12, v0.4.4 on 2026-09-13. Frequent point releases on a 0.x line mean the API can move between them, so pinning a version is the safer default for anything you depend on.

The upgrade path for a normal installation is a single command, tau update. For a checkout-backed editable install, the README is explicit that you must re-run uv tool install --editable --force . after git pull, otherwise the tool environment keeps stale metadata and entry points. That is the main upgrade cost, and it is a documentation-level trap rather than a bug.

Licensing is MIT, declared in pyproject.toml with license = "MIT" and license-files = ["LICENSE"]. MIT is permissive and imposes no copyleft obligation on your own code. That is a statement about the licence text, not legal advice; if you redistribute Tau inside a product, read the LICENSE file in the repository and check how the dependencies are licensed.

Editorial conclusion

Adopt Tau if you want a coding agent small enough to read end to end, or if you are building your own frontend on top of AgentHarness. Skip it if you need a mature plugin ecosystem, a stable library API, or a supported path to Python 3.11 and older. Before committing, run tau --version, confirm the provider you intend to use appears in the built-in catalog or in your own ~/.tau/catalog.toml, and check the pinned textual>=8.2.8 requirement against your environment.

Frequently asked questions

Official sources

1. huggingface/tau on GitHub
2. License: MIT
3. Project website
4. README
5. Releases