[WIP] Start on a coding agent demo

.gitignore

@@ -216,3 +216,4 @@ __marimo__/
 
 .claude/
 .codex
+.tau/

examples/.test_scripts/check-examples.py

@@ -30,6 +30,12 @@
         ["fastapi", "textual", "websockets"],
         ["."],
     ),
+    (
+        "tau-agent",
+        REPO / "examples" / "tau-agent",
+        ["textual"],
+        ["."],
+    ),
     (
         "temporal-direct",
         REPO / "examples" / "temporal-direct",

examples/tau-agent/.gitignore

@@ -0,0 +1,13 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+
+# Environment
+.env
+.env*.local
+
+# Tau session history
+.tau/

examples/tau-agent/AGENTS.md

@@ -0,0 +1,49 @@
+# AGENTS.md — tau-agent
+
+## Overview
+
+`tau` is a single-process coding-agent TUI built on the `ai` library and
+Textual.  It gives the model seven filesystem/shell tools (read, write,
+edit, bash, grep, find, ls) with an approval gate for mutating
+operations.
+
+## Project layout
+
+```
+tau/
+  app.py        — Textual app, chat loop, approval flow
+  tools.py      — tool definitions (mirrors pi's seven built-ins)
+  session.py    — JSONL session persistence and resume
+pyproject.toml  — project metadata, dependencies, ruff/mypy config
+```
+
+## TODO list
+
+There may be a task list in `.tau/TODO` — check it for current
+priorities and open items.
+
+## Running
+
+```bash
+uv sync          # install deps
+uv run tau       # launch the TUI
+```
+
+## Linting & type-checking
+
+```bash
+uv run ruff check .        # lint
+uv run ruff format --check # format check
+uv run mypy tau            # type-check
+```
+
+## Conventions
+
+- Python ≥ 3.12.
+- Line length: 80 (`ruff` and project style).
+- Lint rule set: E, F, I, UP, B, SIM (see `pyproject.toml`).
+- No workspace jail — the approval gate is the safety mechanism.
+- Approval-gated tools (`write`, `edit`, `bash`) require operator
+  confirmation; reads are auto-approved.
+- Sessions persist as JSONL under `.tau/sessions/`.
+- Commit messages for this subdirectory should be prefixed with `[tau]`.

examples/tau-agent/README.md

@@ -0,0 +1,41 @@
+# tau-agent
+
+`tau` is a coding-agent demo built on the `ai` library.  Single
+process, Textual TUI, streaming replies, pi-style tool surface:
+
+- **`read`** — read files; offset/limit pagination with continuation hints
+- **`write`** — create / overwrite a file
+- **`edit`** — exact-match str_replace, multiple disjoint edits per call
+- **`bash`** — run a shell command in cwd, output truncated to the last 50KB / 2000 lines *(requires approval)*
+- **`grep`** — regex search (skips `.git`, `node_modules`, etc.)
+- **`find`** — glob match
+- **`ls`** — directory listing
+
+Approval-gated tools fire a `ToolApproval` hook; the composer turns
+into a `[y/n]` prompt mid-turn.  Unrelated text typed during a
+pending approval falls through to the message queue — the hook stays
+pending until you give it a y or n.
+
+No workspace jail.  The approval gate is the safety mechanism;
+everything else relies on you watching the prompts.
+
+## Setup
+
+```bash
+uv sync
+```
+
+## Running
+
+```bash
+uv run tau
+```
+
+Type a message, hit enter.  `ctrl+c` to quit.
+
+## Environment
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `AI_GATEWAY_API_KEY` | Vercel AI Gateway API key | — |
+| `TAU_MODEL` | Model id passed to `ai.ai_gateway(...)` | `anthropic/claude-sonnet-4.5` |

examples/tau-agent/pyproject.toml

@@ -0,0 +1,35 @@
+[project]
+name = "tau-agent"
+version = "0.1.0"
+description = "Tau — a coding-agent chat bot demo built with the ai library and Textual"
+requires-python = ">=3.12"
+dependencies = [
+    "ai",
+    "textual>=3.0",
+]
+
+[project.scripts]
+tau = "tau.app:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["tau"]
+
+[tool.uv.sources]
+ai = { path = "../..", editable = true }
+
+[tool.ruff]
+line-length = 80
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]
+
+[dependency-groups]
+dev = [
+    "mypy~=2.1.0",
+    "ruff>=0.15.12",
+]

examples/tau-agent/tau/__init__.py

@@ -0,0 +1 @@
+"""tau — a coding-agent chat bot built on the `ai` library and Textual."""

examples/tau-agent/tau/__main__.py

@@ -0,0 +1,5 @@
+"""Entry point for ``python -m tau``."""
+
+from tau.app import main
+
+main()