Tau: The Open-Source Coding Agent That Teaches You How AI Agents Actually Work

The actual blog post with markdown formatting

If you've ever wondered what's actually happening inside an AI coding assistant when it "thinks," "uses tools," or "remembers" your conversation, you're not alone. The gap between "it just works" and "I understand how it works" is where most developers get stuck. Tau is here to change that.

What Makes Tau Different

Tau is a small but complete Python coding agent designed as a learning resource. Unlike production tools that hide their internals behind abstraction layers, Tau puts everything on display. Every token streamed, every tool call made, every decision point in the agent loop—it's all there, readable like a well-commented textbook.

The project emerged from a simple observation: the best way to learn how something works is to build it yourself, but most "build your own AI agent" tutorials skip the hard parts. Tau doesn't skip anything.

The Three-Layer Architecture

Tau breaks down into three clean layers, each with a distinct responsibility:

The first layer, tau_ai, handles the messy reality of different AI providers. Whether you're using OpenAI, Anthropic, or something else entirely, this layer turns their varying response formats into a consistent stream of events. Think of it as a universal adapter for model output.

The second layer, tau_agent, is the brain. This is where the agent loop lives—the code that decides what to do next, calls tools, manages conversation history, and handles cancellation. It's designed to be reusable, meaning you could swap out the AI provider or the user interface without touching this core logic.

The third layer, tau_coding, is where things get practical. This layer wraps the agent in an actual coding environment with file operations, shell access, persistent sessions, and a Textual-based terminal UI. It's the part you'd actually use day-to-day.

The Event-Driven Philosophy

What really sets Tau apart is its commitment to event streaming over traditional control flow. Instead of buried callbacks and nested if-statements, Tau emits a continuous stream of events you can inspect, test, render, or export. This makes debugging intuitive and learning visual—you can literally watch the agent think.

The flow goes like this: raw tokens and tool requests come in from the model, get normalized into provider-neutral events, flow through the agent loop for decision-making, then output to both a session file (for persistence) and a frontend (for display). Clean, traceable, and debuggable.

Separation of Concerns as a Teaching Tool

One of Tau's most valuable lessons is architectural: keep the brain, the environment, and the face apart. The reusable agent harness shouldn't know anything about terminals, file paths, or Rich rendering. Those are implementation details that belong in outer layers, wrapped around the core logic.

This boundary-first thinking produces code that's easier to understand, test, and modify. More importantly, it makes the project learnable in stages. You can study the provider layer without touching the harness. You can build a TUI without understanding how tool calls work. Each piece has a clear interface and a single job.

What You Can Actually Learn

Tau covers the fundamentals that tutorials usually skip. Provider-neutral streaming interfaces show you how to abstract away the differences between AI APIs. The agent loop demonstrates the request-execute-feedback cycle in its purest form. Typed local tools for file operations and shell commands reveal how AI agents interact with the filesystem.

Sessions persist under ~/.tau/sessions as JSONL files, meaning you can inspect exactly what happened, resume conversations, branch into alternate timelines, or export everything for analysis. This isn't just convenient—it's essential for understanding how context grows and how you might optimize it.

Context management features like compaction and thinking controls address the practical challenge of keeping long conversations efficient. These are real problems everyone building with AI agents eventually faces, and Tau shows you how they're solved.

Why This Matters for Developers

We're entering an era where AI coding assistants are becoming standard tools, not novelties. Understanding how they work underneath isn't just academic—it's becoming a practical skill. When you know how agent loops function, you can build better prompts, debug unexpected behavior, and maybe even contribute to or customize the tools you use.

Tau's approach of "real enough to matter, educational enough to learn" strikes the right balance. You're not building a toy that only works in perfect conditions. You're building something that functions as a legitimate terminal agent while remaining transparent enough to study.

Getting Started

If you're curious about how coding agents are built, Tau offers a structured path. Start with the events flowing through the system, understand how the loop decides what to do, wrap that in a harness with clear boundaries, then add tools and a UI. Each phase builds on the previous one, and each comes with documentation explaining what was added and why.

The project serves as both a working tool and a curriculum. Use it as your actual AI coding assistant if you want, or use it as a reference while building your own implementation. Either way, you'll come away with a deeper understanding of the systems increasingly central to modern development.

Check out the project at twotimespi.dev and join the growing community of developers who prefer understanding their tools to blindly trusting them.