From c2b1e130e9d1d89ee17a449acdb8ecb50e13b62b Mon Sep 17 00:00:00 2001
From: Ollie Agent <ollie@example.com>
Date: Tue, 4 Aug 2026 18:59:48 +0200
Subject: [PATCH] README: document o CLI and o tui

---
 README.md | 47 +++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 45 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index c202a85..28c3316 100644
--- a/README.md
+++ b/README.md
@@ -166,7 +166,49 @@ exec 3<>/mnt/ollie/route; echo 'redesign the auth system' >&3; cat <&3; exec 3>&
 No SSH tunneling, no port forwarding, no API gateway. One mount and every
 session, every tool, every config value is accessible as if local.
 
-### Shell composability
+### Pipe `o`: a composable CLI
+
+The `o` script (`data/scripts/o`) wraps the 9P namespace into a composable CLI:
+
+```sh
+o read chat           # stream chat output
+o prompt              # interactive multi-line REPL
+o tail                # tail chat with block-marker filtering
+o readloop statewait  # block until state changes
+```
+
+Context is set once, then every command addresses the right agent:
+
+```sh
+eval $(o env mysession myagent)
+o read state      # → session/mysession/agent/myagent/state
+o prompt          # REPL for session/mysession/agent/myagent
+```
+
+### `o tui`: an agent terminal in 20 lines of tmux
+
+`o tui` composes `o tail` and `o prompt` into a single tmux layout — no
+framework, no widgets, no IPC. It's two shell commands in two panes:
+
+```
+┌──────────────────────────────────┐
+│  o tail | grep                    │  ← chat stream
+│                                   │
+├──────────────────────────────────┤
+│  o prompt                         │  ← input REPL
+└──────────────────────────────────┘
+Agent state shown in tmux status bar
+```
+
+The prompt REPL supports multi-line input (send with `.` on its own line),
+slash commands (`/stop`, `/model`, `/quit`, etc.), and readline editing.
+Agent state updates the tmux status bar in real time via `statewait`, with
+color-coded background — green for idle, orange for calling, blue for thinking.
+
+This is the entire "frontend": two `o` subcommands, two tmux splits, one
+background `statewait` reader. No SDK, no widget toolkit, no event loop.
+It's the Plan 9 principle in miniature — shell composition over framework
+bloat.
 
 Because operations are file I/O, they compose with the full Unix toolkit:
 
@@ -356,7 +398,8 @@ full variant specification.
 
 | Capability | How |
 |---|---|
-| **Run an agent** | `olliesrv` → any frontend (ellie, KDE, acme) |
+| **Run an agent** | `olliesrv` → any frontend (ellie, KDE, acme, `o tui`) |
+| **Terminal TUI** | `o tui` — tmux + two shell commands, no widgets |
 | **Remote execution** | Set `remote=user@host` in session config |
 | **Multi-agent** | `subagent_spawn` from within a session, or shell scripts |
 | **Code completion** | Read/write `/complete` for fill-in-the-middle |