Tau — A Minimalist Python Coding Agent
A terminal-native coding agent that reads, edits, runs commands, and keeps durable sessions — designed to be read.
- Source repo
- huggingface/tau
- Stars
- ★ 3k
- Last updated
- 5d ago
- License
- MIT
- Primary language
- Python
- FA score
- 53/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformOpenAI API · Claude APIChatGPT · Codex (Partial support)
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A developer wants an in-terminal coding assistant for a local project to explain code, add tests, or fix a stack trace.
- Not a fit if
- Teams stuck on Python versions below 3.12
- Users wanting a mature, feature-complete production tool
- Environments that cannot add uv or extra dependencies
- Source review
- 53/100 · Major gaps
What does this agent do, and when should you use it?
Tau is an MIT-licensed Python project that provides a terminal coding agent harness, built with a 'small, readable' philosophy and intended as a teaching example. It is organized into three layered packages: tau_ai abstracts model providers, tau_agent provides the portable brain (messages, tools, events, loop), and tau_coding wraps it as a real coding app with CLI, TUI, tools, and session storage. Tau runs as a Textual-based interactive TUI or a one-shot print mode, with a core that communicates via typed event streams, decoupled from frontends. Sessions are persisted as JSONL under ~/.tau/sessions/ with resume and branching support. It supports multiple model providers including OpenAI, Anthropic, OpenRouter, and Hugging Face, and allows custom providers via catalog files.
Tau provides a tau command for interactive terminal use or one-shot prompts via -p. It includes built-in coding tools: read, write, edit, and bash for file reading, editing, and shell execution. It manages durable JSONL sessions (under ~/.tau/sessions/), reads project instructions from AGENTS.md and similar, and supports slash commands like /login and /model. It exposes an AgentHarness class in tau_agent for programmatic use.
- A developer wants an in-terminal coding assistant for a local project to explain code, add tests, or fix a stack trace.
- A user needs a single command to automate a script, e.g.,
tau -p "summarize the architecture". - A team wants to maintain sessions for audit or resuming work across contexts.
- A developer wants to learn how coding agents are built by studying the layered code in tau_ai, tau_agent, tau_coding.
- A user needs to integrate a custom model provider by editing a catalog.toml file.
How do you install or deploy this agent?
On macOS/Linux, run curl -LsSf https://twotimespi.dev/install.sh | sh; on Windows PowerShell, run irm https://twotimespi.dev/install.ps1 | iex. Alternatively, use uv tool install tau-ai or pipx install tau-ai. Requires Python 3.12+.
How do you use this agent?
Run tau in the project directory for the interactive TUI, then type requests. Use tau -p "..." for one-shot mode. First, connect a provider with /login, e.g., /login openai. Specify a working directory with --cwd.
What are this agent's strengths and limitations?
- Layered architecture (tau_ai, tau_agent, tau_coding) is clear and extensible.
- Event-driven design allows multiple frontends (TUI, print, custom).
- Sessions are persisted as JSONL with resume and branching.
- Custom providers can be added via catalog.toml without code changes.
- Requires Python 3.12+, which may limit older environments.
- Model provider support depends on external APIs, requiring subscriptions or keys.
- As a teaching project, it may lack advanced features of mature tools.
- The installer installs uv, adding an extra dependency.
How does this agent compare with similar options?
Tau is inspired by Pi's minimalist coding agent, but is implemented in Python, offering a more streamlined implementation.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Tau — A Minimalist Python Coding Agent This agent | 53 · Major gaps | CLIFree + model costs | ★ 3k | 5d ago | Python | OpenAI API · Claude API |
| ClawCodex | 51 · Major gaps | CLIFree + model costs | ★ 911 | today | TypeScript | ChatGPT · OpenAI API · Claude API |
| zerostack | 57 · Major gaps | CLIFree + model costs | ★ 1.7k | 5d ago | Rust | OpenAI API · Claude API |
| MiniCode | 50 · Major gaps | CLIFree + model costs | ★ 1.1k | 10d ago | TypeScript | Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows: installers do not use sudo, tools are ordinary functions, sessions are append-only JSONL, provider/model catalog is customizable, but no explicit implementation or documentation of least privilege, user confirmation, data flow transparency, sensitive data handling, dependency security, external effects, rollback, or source attribution. Deductions: these aspects lack sufficient evidence in the provided files; README descriptions alone are insufficient.
Evidence shows: clear code structure, tests cover core harness functionality, dependency versions are constrained, error handling is tested. Deductions: no direct evidence of dependency availability or failure message quality, and tests were not run in a real environment.
Evidence shows: README describes multiple usage scenarios (interactive TUI, print mode, library use), capability boundaries are clear (core does not depend on frontend), triggers are explicit (CLI, /login, etc.), environment fit (macOS, Linux, Windows). Deductions: no detailed guidance for different user groups, capability boundaries not fully verified in code.
Evidence shows: README is well-structured, install notes are detailed, naming is stable (tau-ai), examples and FAQ are present, MIT license is clear, version number exists (0.3.9). Deductions: no explicit known limitations, no changelog, maintenance responsibility unclear (publisher unverified).
Evidence shows: output is an event stream consumable by multiple frontends, library interface is provided, installation is simple. Deductions: no cost-benefit analysis, marginal value not quantified.
Evidence shows: README claims are broadly consistent with code structure, test files provide some verification. Deductions: no external corroboration, facts and inferences not explicitly separated.
- Publisher identity is unverified; maintenance responsibility and update path are unclear.
- No explicit known limitations; users may lack expectations about edge cases.
- Dependency security is not explicitly assessed; recommend checking for vulnerabilities.
- Install scripts do not use sudo, but their content should be reviewed.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v0.4.8 Tau 0.4.8
Release notes excerpt
New - Expose the active session's provider and model inventory to extensions with ExtensionContext.available_providers and ExtensionContext.available_model_choices. - Expose the session's project-trust decision on ExtensionContext and let hosts restrict child sessions with CodingSessionConfig.allowed_tool_names. Changed - Migrate the documentation website from Hugo to Astro and redesign it as a typeset math paper. Fixed - Retry provider requests on raw TLS record errors (ssl.SSLError) before any content is streamed. …View on GitHub ↗ -
v0.4.7 Tau 0.4.7
Release notes excerpt
New - Archive sessions or whole projects from /resume with Ctrl+Enter without deleting files. Use the Archived tab (F2) and Enter to restore them. Fixed - Restore Option/Alt-arrow word navigation in the prompt inside Herdr, including Kitty Alt+b/Alt+f forwarding. Shift+Option/Alt-arrows select by word. - Create a fresh provider runtime when a new session selects a different provider instead of reusing the previous session's runtime. - Handle Delete correctly in the /resume search field. Upgrade ```bash uv tool upgrade tau-ai ``` …View on GitHub ↗ -
v0.4.6 Tau 0.4.6
Release notes excerpt
Changed - Preview model and thinking shortcuts immediately in the TUI and record only the final selection when sending a prompt; unsent choices remain session-only. - Open /model and /scoped-models from cached choices with a virtualized list, then refresh catalogs in the background after the picker renders. - Limit GitHub Actions token permissions per job and pin workflow actions to immutable commit SHAs. Fixed …View on GitHub ↗