Tau: A Minimalist Python Coding Agent for Your Terminal

Introduction

Tau is a coding agent that lives in your terminal. You can type requests like "explain this repo," "add tests," or "fix this stack trace," and Tau can read files, edit code, run commands, and keep a durable session history while streaming what it is doing. It is also designed as a teaching project, offering a small, readable example of how coding agent systems are built without the complexity of a giant production codebase.

Tau's architecture is layered, separating concerns into tau_ai (model providers), tau_agent (core brain, messages, tools), and tau_coding (CLI, TUI, file/shell tools). This modularity highlights the reusable AgentHarness as the core brain, independent of specific frontends or environments.

Why Use Tau and Its Benefits

Tau offers a robust set of features for developers. It provides an interactive Textual TUI and a non-interactive print mode for scripting. Developers can leverage its built-in coding tools, including read, write, edit, and bash, to interact with their projects. Sessions are durable, stored as JSONL files, allowing for resume and branching.

The agent supports various slash commands for login, model selection, session management, compaction, and export. It can also interpret project instructions from AGENTS.md and custom resources, and supports user skills, prompt templates, and custom TUI themes. Context accounting, manual compaction, and optional automatic compaction are also included, alongside provider-neutral event rendering for various outputs.

The project's philosophy emphasizes small, readable layers, where each package has a single responsibility. Events serve as the primary contract between providers, renderers, and frontends, ensuring portability. The core agent harness remains independent of the CLI or specific UI frameworks. Tools are implemented as ordinary typed functions, and sessions are designed to be durable and inspectable.

Furthermore, Tau can be used as a library, allowing developers to integrate its AgentHarness into their own applications. The harness emits events instead of rendering UI directly, meaning the same core can drive the built-in TUI, print mode, or a frontend you build yourself.

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)

Installation

Tau requires Python 3.12 or newer. The recommended installation method uses uv, which is installed first if necessary.

For macOS and Linux, run:

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

For Windows PowerShell, run:

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

Alternatively, if you have a package manager, you can install Tau directly:

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

Verify the installation with:

tau --version

To upgrade an existing installation, use:

tau update

Examples

To start using Tau, navigate to your project directory and run the tau command:

cd my-project
tau

Then, simply type a request and press Enter, for example:

explain what this project does

For quick prompts or scripting, use the one-shot print mode:

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

Tau requires a model provider. You can connect one by starting Tau and using the /login command:

tau

Inside Tau, type:

/login
/login openai
/model

Tau supports various providers, including OpenAI, Anthropic, OpenRouter, Hugging Face, and custom OpenAI-compatible endpoints, including local models. Refer to the providers guide for more details.