tau-ai 0.1.0

A Python implementation of a minimalist Pi-style coding-agent harness.

A minimalist coding-agent harness in Python, inspired by Pi and built as a teaching project.

Documentation · Getting started · Architecture notes · Roadmap

---

What is Tau?

Tau is a Python implementation of the minimalist coding-agent harness architecture popularized by Pi. It is both:

1. a usable terminal coding agent, and
2. a readable, phase-by-phase reference implementation for learning how coding agents are assembled.

The project intentionally keeps the core pieces small and explicit: model providers stream events, an agent loop turns those events into tool execution and transcript updates, a reusable harness owns state, and the coding app adds local files, shell tools, sessions, skills, commands, and terminal frontends.

tau_ai       provider/model streaming layer
tau_agent    portable agent harness, loop, tools, events, sessions
tau_coding   CLI app, resources, skills, commands, sessions, UI integration

The central design boundary is:

AgentHarness = reusable agent brain
AgentSession = coding-agent environment
TUI          = one possible frontend

Tau should make the architecture legible. If you want to understand how a coding agent works without starting from a large production codebase, this repository is for you.

Why Tau exists

Tau is being built as an effort to teach how to create coding agents.

The philosophy is:

• Small layers beat magic. Each package has a clear job and can be explained independently.
• Events are the contract. The agent harness emits provider-neutral events; renderers and TUIs consume them.
• The core stays portable. tau_agent does not depend on Textual, Rich, shell config directories, slash commands, or application-specific resources.
• Tools are ordinary typed functions. File and shell capabilities are exposed through explicit schemas and deterministic result objects.
• Sessions are durable and inspectable. Tau stores append-only JSONL session transcripts under ~/.tau/sessions/.
• Documentation follows implementation. The project is developed in small, documented phases so readers can trace how the system grows.

Pi is the design inspiration; Tau is the Python learning path.

Current capabilities

Tau currently includes:

• an installable tau console command
• a Textual interactive TUI
• non-interactive print mode for one-shot prompts
• OpenAI-compatible, Anthropic, OpenAI Codex subscription, OpenRouter, and Hugging Face provider support through provider configuration
• provider retry/backoff events and thinking/reasoning deltas
• built-in local coding tools: read, write, edit, and bash
• durable per-project sessions and session resume
• session tree branching and HTML/JSONL export
• slash commands, model picker, theme picker, and autocomplete
• skills, prompt templates, and AGENTS.md project-context discovery
• context accounting, manual compaction, and optional automatic compaction
• Rich/plain/json/transcript rendering paths for print-mode output
• a deterministic fake provider used by tests

Tau is still evolving. Expect the command surface and internals to improve as the roadmap progresses.

Install

Tau targets the Python version declared in pyproject.toml and uses uv for the recommended workflow.

Install from GitHub:

uv tool install tau-ai
tau --version

Install from a local checkout:

git clone https://github.com/alejandro-ao/tau.git
cd tau
uv tool install --editable .
tau --version

For development:

uv sync --dev
uv run tau --version

First run

Start the interactive terminal UI:

tau

Start the TUI and submit the first prompt immediately:

tau "explain this repository"

Run a one-shot non-interactive prompt:

tau -p "summarize the architecture"

Choose a configured provider/model:

tau --provider openai --model gpt-4.1 "review this codebase"
tau --provider local --model qwen -p "list the main modules"

Use another working directory for coding tools:

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

Configure a model provider

The easiest path is from inside the TUI:

/login
/login openai
/login openai-codex
/logout
/logout openai
/model

/login can save API-key credentials for built-in providers or authenticate an OpenAI Codex subscription account with OAuth. Credentials are stored in ~/.tau/credentials.json with private file permissions. Provider metadata lives in ~/.tau/providers.json. /logout removes only credentials saved in Tau's credentials.json; environment variables and provider configuration are unchanged.

You can also configure an OpenAI-compatible provider from the CLI:

tau --provider local \
  --base-url http://localhost:11434/v1 \
  --api-key-env LOCAL_API_KEY \
  --model qwen \
  setup

Then run:

export LOCAL_API_KEY="..."
tau --provider local

Useful provider commands:

tau providers

See docs/providers.md and docs/configuration.md for details.

Working in the TUI

Common slash commands:

Command	Purpose
/login [provider]	Save or refresh provider credentials.
/logout [provider]	Remove Tau-saved provider credentials.
/model	Choose the active provider/model.
/scoped-models	Pick models available for quick cycling.
/session	Show session and context information.
/resume [session-id]	Resume a previous session.
/tree	Branch from a previous session entry.
/name <new name>	Rename the current session.
/compact <summary>	Replace active context with a manual summary.
/export [--format html|jsonl] [destination]	Export the current session.
/reload	Reload local resources and project context.
/theme [name]	Show or set the TUI theme.
/hotkeys	Show common keyboard shortcuts.
/quit	Exit the session.

Important TUI behavior:

• Click anywhere in the main TUI to return keyboard focus to the prompt input.

Common shortcuts:

Shortcut	Action
Enter	Submit prompt.
Shift+Enter	Insert newline.
Alt+Enter	Queue a follow-up while the agent is running.
Esc	Cancel active run.
Ctrl+K	Open slash-command completions.
Ctrl+R	Open session picker.
Shift+Tab	Cycle thinking mode.
Ctrl+T	Toggle thinking-token display.
Ctrl+O	Collapse or expand tool output.
Ctrl+P	Cycle scoped models.
Ctrl+D	Quit.

Sessions, resources, and files

Tau stores durable app state in your home directory:

~/.tau/providers.json       provider metadata
~/.tau/credentials.json     saved API keys and OAuth credentials
~/.tau/tui.json             TUI theme/keybinding settings
~/.tau/sessions/            append-only JSONL session transcripts
~/.tau/skills/              user Tau skills
~/.tau/prompts/             user prompt templates
~/.tau/AGENTS.md            user Tau instructions

Tau also reads user-level .agents resources and project-local resources from the active working directory, including AGENTS.md, .tau/, and .agents/ locations. This lets a project teach Tau how it should behave without changing Tau's core harness.

Use Tau as a library

Tau's reusable brain lives in tau_agent:

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)

That harness is deliberately independent of the CLI/TUI. You can build another frontend by consuming the same event stream.

Development

Set up the repository:

uv sync --dev

Run checks:

uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run mypy

Run Tau locally:

uv run tau
uv run tau -p "explain this repo"

Run the documentation site (Astro Starlight, in website/):

cd website
bun install
bun run dev

Then open http://localhost:4321/tau/. Build the static site with bun run build (output in website/dist/).

Documentation

The user-facing docs are published at https://twotimespi.dev/. Their source lives in website/src/content/docs/:

• What is Tau?
• Quickstart
• Core concepts
• Guides — the TUI, sessions, providers & models, skills & prompts, context
• Reference — CLI, slash commands, keybindings, configuration, tools
• How Tau works — architecture, the agent loop

Contributor build journals (phase notes, design docs, ADRs) live in dev-notes/ and are intentionally not published.

Project status

Tau is under active development. The implementation roadmap is tracked in GitHub issue #1, and the notes under dev-notes/architecture/ record the completed phases.

The goal is not to hide complexity. The goal is to make each part of a coding agent visible, testable, and understandable.