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 — это Python-порт минималистичного кодинг-агента Pi от Hugging Face: приложение для терминала, которому можно попросить объяснить репозиторий, добавить тесты или починить стек-трейс, а оно читает файлы, правит код, запускает команды и показывает в реальном времени, что делает.
Это готовый инструмент или скорее кодовая база для изучения?И то и другое. Это работающий CLI/TUI кодинг-агент, но также специально сделанный читабельным учебный проект, разбитый на небольшие пакеты с одной задачей каждый, — так что можно разобраться, как устроена система кодинг-агента, не продираясь через огромную продакшн-кодовую базу.
Как его установить и начать пользоваться?Установите из PyPI как tau-ai (ставится команда tau) через shell-установщик на macOS/Linux или установщик PowerShell на Windows — оба используют uv, не требуют sudo и нуждаются в Python 3.12+; также подходит conda-forge через pixi. Затем запустите tau внутри своего проекта и подключите провайдера через /login.
Мне нужен API-ключ Anthropic, чтобы им пользоваться?Нет — вы подключаете того провайдера, который у вас есть: OpenAI, Anthropic, авторизацию по подписке OpenAI Codex, OpenRouter, Hugging Face или любой свой эндпоинт, совместимый с OpenAI, включая локальные модели.
Есть ли подводные камни при установке?Главный касается устанавливаемых в режиме editable из клона репозитория: после git pull нужно заново выполнить команду uv tool install, иначе метаданные пакета и точки входа не обновятся, и tau --version может по-прежнему показывать старую версию.
Где хранится история моих сессий?На вашем own диске: история хранится как append-only 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 есть одноразовый print-режим для скриптов и быстрых запросов, а нейтральный к провайдеру поток событий можно вывести как 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