An educational coding-agent project
Learn how coding agents are built.
Tau is a small Python coding agent you read like a textbook. Watch it stream model output, call tools, manage sessions, and grow into a terminal UI — one readable layer at a time.
No hidden machinery. Every moving part is on the page.
learnagent architecture
readsmall Python layers
runa real terminal agent
01
3-layers
A coding agent as a curriculum
Ⅰ tau_ai
Models become streams
Provider adapters turn model responses into provider-neutral events the rest of the agent consumes.
Ⅱ tau_agent
The agent loop
The reusable harness: messages, tools, transcript state, cancellation, queued prompts, sessions.
Ⅲ tau_coding
It becomes useful
The coding environment: files, shell, durable sessions, skills, slash commands, and a Textual TUI.
no black boxes
Every moving part is visible.
Tau answers the questions tutorials skip: What is an agent loop? Where do tool calls come from? How does the transcript grow? How do sessions survive the process exiting?
model streamtokens, tool requests, thinking deltas
↓
event streamthe contract between layers
↓
agent loopdecide, call tools, update transcript
↓
sessioninspectable JSONL history
frontendprint, Rich, or TUI
the boundary
Separate the brain, the environment, and the face.
The whole lesson is the boundary. A reusable harness must not depend on the terminal, file paths, or Rich rendering. Those wrap the harness — they never live inside it.
02
the skills
What you can learn from Tau
Provider-neutral streaming interfaces
Agent loops that request and execute tools
Typed local tools for read, write, edit, and bash
Durable sessions under ~/.tau/sessions
Session resume, branching, JSONL export, and HTML export
Project instructions, skills, and prompt templates
Slash commands and model/provider selection
Context accounting, compaction, and thinking controls
How to keep Textual behind a UI adapter boundary
03
how we think
Educational principles
Small layers beat magic
One job per package. Study the provider layer, harness, and coding app on their own.
Events make agents teachable
The agent emits a stream you can render, test, and export — not control flow buried in callbacks.
Real enough to matter
Educational, not a toy. Run it as a real terminal agent while reading the code behind it.
Docs follow implementation
Built phase by phase, each with notes on what was added, why, and how it fits.
the origin
Inspired by Pi, written as a Python learning path.
Pi is the minimalist coding-agent harness this project borrows its architectural lesson from — keep the harness, the environment, and the UI apart. Tau isn't a line-by-line port; it's an educational Python take on the same core ideas.
A map for building your own agent: start with events, add a loop, wrap it in a harness, then give it tools and a UI.