# Tau

> A small, readable terminal coding agent and educational project that teaches how coding agents are built, with a layered architecture of provider adapters, agent harness, and coding environment.

Tau is a terminal coding agent published on PyPI as `tau-ai` and released under the MIT License. Created by Alejandro AO and hosted under the Hugging Face GitHub organization, it is designed to be both a functional coding assistant and a teaching tool for understanding how coding agents work from the inside out. The project is under active development, with its implementation roadmap tracked publicly on GitHub.

## What It Is

Tau is a Python coding agent that runs in your terminal and accepts natural-language requests like "explain this repo", "add tests", or "fix this stack trace". It can read files, edit code, run shell commands, and maintain durable session history while streaming its activity. Beyond being a working tool, Tau is explicitly designed to be read — its layered architecture makes every moving part visible so developers can study how a coding-agent system is structured without wading through a large production codebase.

## Three-Layer Architecture

Tau is split into three packages with a strict dependency direction:

- **`tau_ai`** — translates model provider responses into a provider-neutral typed event stream
- **`tau_agent`** — the portable agent brain: messages, tools, events, the agent loop, harness, and session primitives
- **`tau_coding`** — wraps the brain as a real coding app with CLI, TUI, file/shell tools, provider config, project instructions, skills, and on-disk sessions

The key design rule is that the reusable `AgentHarness` core does not depend on Textual, Rich, local config paths, slash commands, or rendering. Frontends consume events; they never live inside the harness.

## What Tau Can Do

- Interactive Textual TUI and non-interactive print mode for scripts
- Built-in coding tools: `read`, `write`, `edit`, and `bash`
- Durable JSONL sessions under `~/.tau/sessions/` with resume, branching, and HTML export
- Slash commands for login, model selection, sessions, compaction, export, and theme
- Project instructions from `AGENTS.md`, `.tau/`, and `.agents/` resources
- User skills and prompt templates
- Context accounting, manual and automatic compaction, and thinking controls
- Provider support for OpenAI, Anthropic, OpenAI Codex, OpenRouter, Hugging Face, and custom OpenAI-compatible endpoints including local models

## Educational Design

Tau is built around a set of explicit pedagogical principles. Small layers beat magic — each package has one job and can be studied independently. Events are the contract between layers, making the agent's behavior renderable, testable, and exportable rather than buried in callbacks. The project documentation follows the implementation phase by phase, and `dev-notes/` preserves a build journal explaining what was added, why, and how it fits. The project describes itself as "educational, not a toy" — real enough to use as a daily terminal agent while remaining readable as a learning resource.

## Setup Path

Tau installs via `uv` from PyPI:

```
uv tool install tau-ai
tau --version
```

It can also be cloned and run locally for development. After installation, run `tau` from any project directory, then use `/login` to connect a model provider. One-shot print mode (`tau -p "..."`) works for scripts and quick prompts without launching the TUI.

## Current Status

The repository was created in June 2026 and has accumulated over 420 stars and 49 forks as of early July 2026. The project is under active development with 26 open issues and a public roadmap tracked in GitHub issue #1. Documentation is published at twotimespi.dev and built with Astro/Starlight.

## Features
- Terminal coding agent with interactive Textual TUI
- Provider-neutral typed event stream architecture
- Built-in coding tools: read, write, edit, bash
- Durable JSONL sessions with resume and branching
- Session HTML export
- Slash commands for login, model selection, compaction, and more
- Project instructions from AGENTS.md and .tau/ resources
- User skills and prompt templates
- Context accounting and manual/automatic compaction
- Thinking controls
- Support for OpenAI, Anthropic, OpenAI Codex, OpenRouter, Hugging Face, and custom OpenAI-compatible endpoints
- Local model support
- Non-interactive print mode for scripts
- Usable as a Python library via AgentHarness API
- Provider-neutral event rendering for Rich, plain text, JSON, and custom frontends

## Integrations
OpenAI, Anthropic, OpenAI Codex, OpenRouter, Hugging Face, Custom OpenAI-compatible endpoints, uv, Textual, Rich, PyPI

## Platforms
CLI, API, DEVELOPER_SDK

## Pricing
Open Source

## Links
- Website: http://twotimespi.dev/
- Documentation: https://twotimespi.dev/quickstart/
- Repository: https://github.com/huggingface/tau
- EveryDev.ai: https://www.everydev.ai/tools/tau-ai