tau README

The project's README from github.com/huggingface/tau. As one markdown file: README.md.

Tau — a Python coding-agent harness inspired by Pi

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

Documentation · Quickstart · Architecture · PyPI · Roadmap

Join the Tau Discord community →

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

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, Anthropic, OpenAI Codex subscription auth, OpenRouter, Hugging Face, and custom OpenAI-compatible endpoints, including local models. See the providers guide.

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

Philosophy

Tau follows a few rules:

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

Tau is under active development. The implementation roadmap is tracked in GitHub issue #1.

License

Tau is released under the MIT License.

tau (huggingface/tau)

Searching Database…

3K ·GitHub
Tau
这是什么？Tau 是 Hugging Face 把极简编码代理 Pi 移植成 Python 的版本——这是一个终端应用，你可以让它讲解一个代码库、添加测试或修复堆栈报错，它会读取文件、修改代码、运行命令，并实时显示它正在做什么。
它是一个成品工具，还是更像一份用来学习的代码库？两者都是。它是一个能用的 CLI/TUI 编码代理，但也是一个刻意写得易读的教学项目，被拆成许多只做一件事的小包，所以你可以研究一个编码代理系统是如何搭建的，而不用在庞大的生产级代码库里翻来翻去。
我怎么安装并开始使用它？以 tau-ai 的名字从 PyPI 安装（会装出一个 tau 命令），在 macOS/Linux 上用 shell 安装脚本，在 Windows 上用 PowerShell 安装脚本——两者都使用 uv，不需要 sudo，且要求 Python 3.12+；通过 pixi 从 conda-forge 安装也可以。然后在你的项目里运行 tau，并用 /login 连接一个模型服务商。
用它需要 Anthropic 的 API 密钥吗？不需要——你有什么服务商就用哪个：OpenAI、Anthropic、OpenAI Codex 订阅登录、OpenRouter、Hugging Face，或任何自定义的 OpenAI 兼容接口，包括本地模型。
安装上有什么坑需要提前知道？最主要的一个坑出现在从代码检出目录做可编辑安装的情况：执行 git pull 之后必须重新运行 uv tool install 命令，否则包的元数据和入口点不会刷新，tau --version 可能仍显示旧版本。
我的会话历史存在哪里？存在你自己的磁盘上：历史以追加写入的 JSONL 形式保存在 ~/.tau/sessions/ 下，你可以恢复、分叉和查看这些记录，压缩也从不改写已保存的记录。
可以免费使用吗？可以——采用 MIT 许可证，可以免费使用、修改和再分发。
在一个会话里它能做什么？内置读取、写入、编辑和 bash 工具；提供用于登录、选择模型、会话管理、压缩、导出和主题的斜杠命令；会自动读取 AGENTS.md、.tau/ 和 .agents/ 里的项目说明；还支持用户技能、提示词模板、自定义 TUI 主题，以及手动或自动的上下文压缩。
代码库是怎么组织的？分为三个各司其职的层：tauai 把各家模型服务商统一转换成与服务商无关的事件流，tauagent 是可移植的“大脑”（消息、工具、事件、循环、harness、会话），taucoding 则把它包装成一个真正的编码应用，带 CLI、TUI、文件和 shell 工具以及落盘的会话。核心部分完全不碰 Textual 或 Rich——前端只是消费带类型的事件，所以你完全可以自己写一个前端。
我能添加自己的服务商或模型吗？可以——放一个 ~/.tau/catalog.toml，用和内置目录（src/taucoding/data/catalog.toml）相同的格式，你的服务商和模型就会出现，不需要改任何代码。
有没有供脚本使用的非交互模式？有——除了交互式的 Textual TUI，还有一个一次性输出模式，适合脚本和快速提问；而且这个与服务商无关的事件流可以渲染成 Rich 输出、纯文本、JSON 或完整记录。
What are similar projects?headroom, crush, ordewell, Proteus, claw-code, OpenHarness, DeepCode, Baize
Which topics is it in?minimal, pi-coding-agent, educational, agent-harness, python-library, tui, openai-compatible, local-llm, huggingface, anthropic, coding-agent, openai
Creator
huggingface
Size
15.8 MB
Stars
3K
Updated
CommitOct 14Releasev0.4.8Oct 14
Age
4mo
Commits · 90 Days