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

Hugging Face released Tau, a minimalist terminal coding agent published on PyPI as tau-ai, requiring Python 3.12 or newer. Tau is structured in three layers — tau_ai for provider-neutral model streams, tau_agent for the reusable agent brain, and tau_coding for the CLI/TUI coding app — and supports OpenAI, Anthropic, OpenAI Codex subscription auth, OpenRouter, Hugging Face, and custom OpenAI-compatible endpoints including local models. Hugging Face describes Tau as a teaching project for understanding the shape of a coding-agent system without starting from a giant production codebase.

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 .