Tau Exposes Coding-Agent Architecture Through Three Readable Python Layers
Alejandro Ao presents Tau, a small Python coding agent, as an educational reference rather than a competitor to established tools such as Pi or OpenCode. He argues that Tau’s value is legibility: its three-layer architecture separates provider-neutral model streaming, the reusable agent loop, and the coding-specific terminal environment so developers can see how tools, sessions, model calls, and UI behavior fit together. The project is meant to be read, modified, and extended as a way to understand how coding agents work.
Tau is meant to expose the agent, not hide it
Alejandro AO presents Tau as a coding agent built for legibility. The goal, he says, is not to compete with established agents such as Pi or OpenCode, but to make the moving parts of a coding agent readable enough that developers can understand them, modify them, and build from them.
The objective of this project is not to make it compete with established agents like Pi or open code, but to use it as an educational resource to help you understand how coding agents actually work.
Tau is explicitly modeled on Pi: “basically the same architecture,” with a minimalist system, similar default tools, and a mirrored design, but implemented in Python and made “a little bit more minimal.” Tau’s homepage describes it as “a small Python coding agent you read like a textbook,” designed to show model streaming, tool calls, session management, and a terminal UI “one readable layer at a time.” The site’s promise is direct: “No hidden machinery. Every moving part is on the page.”
That posture determines the shape of the project. Tau is introduced less as a finished productivity surface than as an inspectable harness. Alejandro says upcoming tutorials will explain design decisions and show how to build extensions, user interfaces, and alternate harnesses by mirroring Tau’s architecture.
A social post shown during the introduction reinforces the positioning. Mario Zechner describes Tau as “basically pi, but more minimal for educational purposes and in python,” calling it a “great educational resource.” Alejandro notes that Mario has given the project his blessing.
The architecture is split into three readable layers
Tau is organized around three Python layers: tau_ai, tau_agent, and tau_coding. Alejandro uses this division to separate model access, agent-loop mechanics, and coding-agent product behavior.
| Layer | Role | What it contains |
|---|---|---|
| tau_ai | Provider-neutral model streaming | Adapters that normalize model responses into events |
| tau_agent | Reusable agent loop | Messages, tools, transcript state, sessions, cancellation, queued prompts |
| tau_coding | Coding-agent environment | Files, shell, durable sessions, skills, slash commands, system prompt, Textual TUI |
The lowest layer, tau_ai, “uniformizes” model providers. Its job is to turn different inference providers into a common stream of provider-neutral events that the rest of the agent can consume. In the website language shown on screen: “Models become streams.”
The middle layer, tau_agent, is the reusable agent loop or harness. Alejandro describes it as the part that makes Tau “an actual agent loop”: it sends the user’s query to the language model, executes tools when the model calls them, appends tool results and new messages to the session, and continues looping until the task finishes or the model returns a final response. The website summary lists its concerns as messages, tools, transcript state, cancellation, queued prompts, and sessions.
The top layer, tau_coding, is where the harness becomes a coding agent. It contains the terminal user interface, tool definitions, durable sessions, skills, slash commands, session persistence, compaction behavior, context files, and the rest of the user experience. Alejandro says this layer is “a little bit more complex” because it turns the underlying harness into a practical coding environment rather than just a generic loop around an LLM.
The point of the split is approachability. Alejandro repeatedly describes the project as minimalist and straightforward, with a structure that lets a reader see where provider abstraction ends, where the agent loop begins, and where the coding-specific environment is added.
The default interface keeps the working surface small
After installation, Tau runs from the terminal. Alejandro shows the install command as uv tool install tau-ai, followed by launching the agent with tau.
The terminal UI opens with a sidebar showing the active session, selected provider, selected model, current thinking mode, the number of tools, the number of skills, loaded context, and available prompts. In the example shown, the session uses an OpenAI Codex provider with gpt-5.5, thinking mode set to medium, four tools, five skills, and AGENTS.md as a loaded context file.
The default tool set is deliberately small: read, write, edit, and bash. Alejandro says users can create their own tools, and that future videos will cover how to do that, but the base distribution stays minimal. He also describes the tools as inspired by Pi’s tools — “basically a Python implementation” of them.
The interface exposes skills and custom prompts as modular additions rather than fixed product surface area. In Alejandro’s own project, the visible skills include explore-project, find-skills, firecrawl-parse, firecrawl-scrape, and firecrawl-search. The prompts shown include issue, merge-pr, prune, and review.
Configuration is part of the agent interface, not a hidden prelude
On first install, Tau has no provider configured. Alejandro shows /login, which opens a provider menu with OpenAI, Anthropic, OpenRouter, and Hugging Face Inference Providers. For Hugging Face Inference Providers, he says users can add a Hugging Face API key and use models such as GLM 5.2, Minimax, or Kimi.
Model selection also stays inside the TUI. /model selects an active model; /scoped-models lets the user mark shortcut or favorite models. Alejandro adds GLM 5.2, Kimi K2.7, and Minimax M3 in the demonstration. Once models are scoped, Control-P cycles among them.
Thinking mode is exposed in the same working surface. Alejandro shows levels including medium, high, extra high, and off, while noting that availability depends on the model being used. The TUI indicates when thinking is active and shows Ctrl+T as the shortcut to show thinking tokens.
Provider login, model switching, scoped favorites, and thinking controls all live inside the coding session. Tau presents them as part of the agent’s working interface rather than as separate setup machinery outside it.
Durable sessions make the agent more than a one-shot wrapper
Tau stores sessions and lets users resume them. Alejandro demonstrates /resume, which opens a session list with timestamps, model names, and labels such as default-custom-prompts, autocomplete-window-shrink, release-0.1.1, and improve-repo-security. He selects a session tied to a pull request he had been working on.
The resumed session concerns a PR that adds custom prompts for issues and pull-request creation. Alejandro asks Tau to “validate and merge this PR on GitHub.” The terminal output includes shell and GitHub CLI activity, including a gh pr edit command, a gh pr view command, an updated PR URL, and a note that validation still passes with “6 passed.” It shows Tau working through the PR context and validation; it does not show a completed merge.
The PR example connects the top-level coding environment to the underlying agent loop. The agent reads project state, runs commands, edits PR metadata, appends results to the session, and continues the task. Alejandro’s explanation of the architecture maps directly onto the visible behavior in the TUI.
The session model matters because Tau is framed as a coding agent, not just a chat interface. Resumable sessions, context files, prompts, tools, shell access, and model switching are all part of the coding-agent environment that sits above the general harness.
The project is also a curriculum for contributors
Alejandro invites contributions, but frames contributing as part of the learning model. He says the project is intentionally educational and that he will produce tutorials when a design or architecture detail deserves more attention. Planned tutorials include creating a terminal UI, building other kinds of interfaces, and deploying an agent as a background service with a gateway so it can be used over Telegram or Slack.
The GitHub source layout shown on screen reinforces the project’s teaching structure. Under src, the repository contains tau_agent, tau_ai, and tau_coding, matching the architectural split he describes. Alejandro says the source code is “very simple” and that the intent is to keep it modular and easy to build on top of.
He also mentions possible future additions such as skills, while emphasizing that Tau should remain approachable. The system prompt, tools, TUI, sessions, and coding-agent behavior live in the top layer; the lower layers remain reusable. For a developer trying to understand coding agents, that separation is the lesson: a model provider interface is not the same thing as an agent loop, and an agent loop is not yet a coding agent until it is placed inside an environment with tools, files, shell access, persistence, and user interaction.