ffwf-tau-coding-agent 0.9.2__tar.gz

ffwf_tau_coding_agent-0.9.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fight Fire with Fire Robotics, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ffwf_tau_coding_agent-0.9.2/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: ffwf-tau-coding-agent
+Version: 0.9.2
+Summary: τ-coding-agent: Interactive TUI (Textual) + CLI
+Author: Fight Fire with Fire Robotics, LLC
+License-Expression: MIT
+Project-URL: Homepage, https://ffwfrobotics.github.io/tau/
+Project-URL: Documentation, https://ffwfrobotics.github.io/tau/
+Project-URL: Repository, https://github.com/jmccardle/tau
+Project-URL: Issues, https://github.com/jmccardle/tau/issues
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ffwf-tau-agent-core==0.9.2
+Provides-Extra: tui
+Requires-Dist: textual>=0.47; extra == "tui"
+Requires-Dist: rich; extra == "tui"
+Provides-Extra: jmfts
+Requires-Dist: ffwf-tau-jmfts==0.9.2; extra == "jmfts"
+Provides-Extra: dev
+Requires-Dist: ffwf-tau-coding-agent[jmfts,tui]==0.9.2; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy==2.1.*; extra == "dev"
+Requires-Dist: textual-dev; extra == "dev"
+Requires-Dist: pytest-textual-snapshot; extra == "dev"
+Requires-Dist: cairosvg; extra == "dev"
+Dynamic: license-file
+
+# ffwf-tau-coding-agent
+
+The interface of **Tau**, a programmable coding agent harness: the `tau`
+command, its Textual terminal UI, and the headless run paths behind `tau -p` and
+`tau --mode rpc`.
+
+Tau began as a Python port of the TypeScript project
+[pi-mono](https://github.com/badlogic/pi-mono), which is still read as the
+reference implementation when porting or debugging; it now diverges from pi
+deliberately in several places.
+
+## Install
+
+```bash
+pip install ffwf-tau-coding-agent            # headless: the CLI, `tau -p`, `--mode rpc`
+pip install 'ffwf-tau-coding-agent[tui]'     # add the interactive TUI
+```
+
+Python 3.11 or newer. Pulls in `ffwf-tau-agent-core`, and through it
+`ffwf-tau-llm`. Note the `ffwf-` prefix: `tau-llm` and `tau-ai` on PyPI are
+unrelated projects.
+
+| Extra | Adds | Needed for |
+|---|---|---|
+| `ffwf-tau-coding-agent[tui]` | `textual`, `rich` | the interactive TUI. `tau -p` runs a full turn without it |
+| `ffwf-tau-coding-agent[jmfts]` | `ffwf-tau-jmfts` | `--store jmfts` session storage |
+
+**The interface is an extra, not a base dependency.** A headless install is 15
+packages and 13 MB; adding `[tui]` makes it 27 packages and 31 MB. Both extras
+report their own absence — asking for the TUI or for `--store jmfts` without the
+matching extra fails with the install command you need, not a traceback.
+
+### Two names for one command
+
+The install puts **both `tau` and `ffwf-tau`** on your PATH. They are the same
+entry point, not a link: each is a wrapper pip owns and removes on uninstall.
+
+Type `tau`. PyPI reserves distribution names but not command names, and at least
+one unrelated project ships its own `tau`; in an environment holding both,
+whichever installed last owns the name and neither pip nor uv says a word.
+`ffwf-tau` cannot be taken, which makes it the right name inside scripts,
+systemd units, and Dockerfiles. If `tau --version` does not report τ,
+`ffwf-tau --version` will.
+
+## Run
+
+```bash
+tau                                 # interactive TUI
+tau -p "list the files here"        # headless: print a transcript, exit
+tau -p --mode json "..."            # headless: JSONL lifecycle events instead of text
+tau --mode rpc                      # drive τ as a subprocess over stdio (JSON-RPC 2.0)
+tau -e permission_gate.py           # load an extension from a path
+tau --help                          # the exact contract; treat this page as the stale one
+```
+
+`tau -p` and `tau --mode rpc` both write and resume real sessions under
+`~/.tau/sessions/`, so a headless run appears in the TUI's sidebar and can be
+picked up interactively later. `--no-session` means nothing is persisted.
+
+Flags worth knowing: `-m/--model`, `-t/--tools` and `-nt/--no-tools`,
+`-e/--extension PATH`, `--thinking {off,minimal,low,medium,high,xhigh}`,
+`-c/--continue`, `--session REF`, `--fork REF`, `--store {file,jmfts}`.
+
+## Configure
+
+On first run τ writes `~/.tau/config.json` from a default shipped inside the
+package. It holds the `models` map that `--model` resolves names against, plus
+per-extension config and the `session_store` block. A model entry names the
+provider, the base URL, and the context window, so pointing τ at a local
+OpenAI-compatible server (vLLM, llama.cpp, Ollama) is a config edit rather than
+a code change.
+
+## The TUI
+
+Built on [Textual](https://textual.textualize.io/). Streamed text renders at
+30 Hz; tool calls and their results appear as their own blocks.
+
+| Key | Action |
+|---|---|
+| `Ctrl+Enter` | send the message |
+| `Ctrl+B` | toggle the session sidebar |
+| `Ctrl+N` | new chat |
+| `Ctrl+G` | browse the conversation tree |
+| `Ctrl+Z` | roll back the last turn |
+| `Ctrl+R` / `Ctrl+T` | show or hide reasoning / tool blocks |
+| `Ctrl+E` | extensions |
+| `Ctrl+P` | command palette |
+| `Escape` | cancel the current generation |
+
+**The sidebar and the tree browser are two different things.** The sidebar picks
+*which session to open* — a flat list grouped by date. `Ctrl+G` opens a browser
+over the branch structure *inside the current conversation*, where you navigate
+to an earlier node, summarise a branch, or elide a span. Typed commands cover
+the rest: `/compact`, `/tree`, `/fork`, `/extensions`.
+
+## Why it is a separate package
+
+Everything here is presentation and process management. The agent lives in
+`ffwf-tau-agent-core`, which has no Textual dependency and never imports this
+package. `ffwf-tau-jmfts` is a peer rather than a dependency: `--store jmfts`
+imports it lazily and fails at startup if it is absent, never falling back to
+files without saying so.
+
+If you want the agent rather than the interface, use the runtime directly:
+
+```python
+import asyncio
+from tau_agent_core import create_agent_session
+
+
+async def main():
+    session = create_agent_session(model="gpt-4o", tools=["read", "bash"])
+    print(await session.prompt("What is in this directory?"))
+
+
+asyncio.run(main())
+```
+
+## Docs
+
+- `docs/tau-coding-agent.md` — design notes for this package.
+- `docs/CLI-PLAN.md` — the flag set and its status.
+- `docs/REMOTE-CONTROL.md`, `docs/RPC-PROTOCOL.md` — `--mode rpc`.
+- `docs/EXTENSIONS-WALKTHROUGH.md` — writing an extension to load with `-e`.
+
+Repository: <https://github.com/jmccardle/tau>
+
+## The rest of Tau
+
+| Distribution | Imports as | What it is |
+|---|---|---|
+| `ffwf-tau-llm` | `tau_llm` | the provider and streaming layer |
+| `ffwf-tau-agent-core` | `tau_agent_core` | the agent loop, tools, sessions, extensions |
+| `ffwf-tau-jmfts` | `tau_jmfts` | a JMFTS-backed session store |
+
+MIT © Fight Fire with Fire Robotics, LLC

ffwf_tau_coding_agent-0.9.2/README.md

@@ -0,0 +1,136 @@
+# ffwf-tau-coding-agent
+
+The interface of **Tau**, a programmable coding agent harness: the `tau`
+command, its Textual terminal UI, and the headless run paths behind `tau -p` and
+`tau --mode rpc`.
+
+Tau began as a Python port of the TypeScript project
+[pi-mono](https://github.com/badlogic/pi-mono), which is still read as the
+reference implementation when porting or debugging; it now diverges from pi
+deliberately in several places.
+
+## Install
+
+```bash
+pip install ffwf-tau-coding-agent            # headless: the CLI, `tau -p`, `--mode rpc`
+pip install 'ffwf-tau-coding-agent[tui]'     # add the interactive TUI
+```
+
+Python 3.11 or newer. Pulls in `ffwf-tau-agent-core`, and through it
+`ffwf-tau-llm`. Note the `ffwf-` prefix: `tau-llm` and `tau-ai` on PyPI are
+unrelated projects.
+
+| Extra | Adds | Needed for |
+|---|---|---|
+| `ffwf-tau-coding-agent[tui]` | `textual`, `rich` | the interactive TUI. `tau -p` runs a full turn without it |
+| `ffwf-tau-coding-agent[jmfts]` | `ffwf-tau-jmfts` | `--store jmfts` session storage |
+
+**The interface is an extra, not a base dependency.** A headless install is 15
+packages and 13 MB; adding `[tui]` makes it 27 packages and 31 MB. Both extras
+report their own absence — asking for the TUI or for `--store jmfts` without the
+matching extra fails with the install command you need, not a traceback.
+
+### Two names for one command
+
+The install puts **both `tau` and `ffwf-tau`** on your PATH. They are the same
+entry point, not a link: each is a wrapper pip owns and removes on uninstall.
+
+Type `tau`. PyPI reserves distribution names but not command names, and at least
+one unrelated project ships its own `tau`; in an environment holding both,
+whichever installed last owns the name and neither pip nor uv says a word.
+`ffwf-tau` cannot be taken, which makes it the right name inside scripts,
+systemd units, and Dockerfiles. If `tau --version` does not report τ,
+`ffwf-tau --version` will.
+
+## Run
+
+```bash
+tau                                 # interactive TUI
+tau -p "list the files here"        # headless: print a transcript, exit
+tau -p --mode json "..."            # headless: JSONL lifecycle events instead of text
+tau --mode rpc                      # drive τ as a subprocess over stdio (JSON-RPC 2.0)
+tau -e permission_gate.py           # load an extension from a path
+tau --help                          # the exact contract; treat this page as the stale one
+```
+
+`tau -p` and `tau --mode rpc` both write and resume real sessions under
+`~/.tau/sessions/`, so a headless run appears in the TUI's sidebar and can be
+picked up interactively later. `--no-session` means nothing is persisted.
+
+Flags worth knowing: `-m/--model`, `-t/--tools` and `-nt/--no-tools`,
+`-e/--extension PATH`, `--thinking {off,minimal,low,medium,high,xhigh}`,
+`-c/--continue`, `--session REF`, `--fork REF`, `--store {file,jmfts}`.
+
+## Configure
+
+On first run τ writes `~/.tau/config.json` from a default shipped inside the
+package. It holds the `models` map that `--model` resolves names against, plus
+per-extension config and the `session_store` block. A model entry names the
+provider, the base URL, and the context window, so pointing τ at a local
+OpenAI-compatible server (vLLM, llama.cpp, Ollama) is a config edit rather than
+a code change.
+
+## The TUI
+
+Built on [Textual](https://textual.textualize.io/). Streamed text renders at
+30 Hz; tool calls and their results appear as their own blocks.
+
+| Key | Action |
+|---|---|
+| `Ctrl+Enter` | send the message |
+| `Ctrl+B` | toggle the session sidebar |
+| `Ctrl+N` | new chat |
+| `Ctrl+G` | browse the conversation tree |
+| `Ctrl+Z` | roll back the last turn |
+| `Ctrl+R` / `Ctrl+T` | show or hide reasoning / tool blocks |
+| `Ctrl+E` | extensions |
+| `Ctrl+P` | command palette |
+| `Escape` | cancel the current generation |
+
+**The sidebar and the tree browser are two different things.** The sidebar picks
+*which session to open* — a flat list grouped by date. `Ctrl+G` opens a browser
+over the branch structure *inside the current conversation*, where you navigate
+to an earlier node, summarise a branch, or elide a span. Typed commands cover
+the rest: `/compact`, `/tree`, `/fork`, `/extensions`.
+
+## Why it is a separate package
+
+Everything here is presentation and process management. The agent lives in
+`ffwf-tau-agent-core`, which has no Textual dependency and never imports this
+package. `ffwf-tau-jmfts` is a peer rather than a dependency: `--store jmfts`
+imports it lazily and fails at startup if it is absent, never falling back to
+files without saying so.
+
+If you want the agent rather than the interface, use the runtime directly:
+
+```python
+import asyncio
+from tau_agent_core import create_agent_session
+
+
+async def main():
+    session = create_agent_session(model="gpt-4o", tools=["read", "bash"])
+    print(await session.prompt("What is in this directory?"))
+
+
+asyncio.run(main())
+```
+
+## Docs
+
+- `docs/tau-coding-agent.md` — design notes for this package.
+- `docs/CLI-PLAN.md` — the flag set and its status.
+- `docs/REMOTE-CONTROL.md`, `docs/RPC-PROTOCOL.md` — `--mode rpc`.
+- `docs/EXTENSIONS-WALKTHROUGH.md` — writing an extension to load with `-e`.
+
+Repository: <https://github.com/jmccardle/tau>
+
+## The rest of Tau
+
+| Distribution | Imports as | What it is |
+|---|---|---|
+| `ffwf-tau-llm` | `tau_llm` | the provider and streaming layer |
+| `ffwf-tau-agent-core` | `tau_agent_core` | the agent loop, tools, sessions, extensions |
+| `ffwf-tau-jmfts` | `tau_jmfts` | a JMFTS-backed session store |
+
+MIT © Fight Fire with Fire Robotics, LLC

ffwf_tau_coding_agent-0.9.2/pyproject.toml

@@ -0,0 +1,107 @@
+[project]
+name = "ffwf-tau-coding-agent"
+# The version is not a literal here. Each distribution reads it from its own
+# package's ``__version__``, so the wheel metadata and what the code reports can
+# never disagree -- they are the same line. Bump that line to cut a release.
+dynamic = ["version"]
+description = "τ-coding-agent: Interactive TUI (Textual) + CLI"
+requires-python = ">=3.11"
+readme = "README.md"
+# SPDX expression + the file itself (PEP 639), which is why build-system below
+# needs setuptools >= 77.0.3: earlier versions ignore `license-files` and the
+# wheel ships without the licence text. Each package carries its own copy of the
+# repo-root LICENSE because a wheel is built from one package directory and
+# cannot reach outside it.
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Fight Fire with Fire Robotics, LLC" }]
+dependencies = [
+    "ffwf-tau-agent-core==0.9.2",
+]
+
+[project.optional-dependencies]
+# The interface. `tau -p` (cli.py -> headless.py) never imports textual: the only
+# entry into the Textual app is a lazy `from tau_coding_agent.app import Parley`
+# inside cli._launch_tui, so a headless install runs a full turn -- extensions and
+# all -- with neither library present. Measured: 15 packages / 13 MB without this
+# extra, 27 packages / 31 MB with it.
+#
+# rich belongs here rather than in the base: its importers are app.py,
+# chat_widgets.py and testing/render.py, and every one of them imports textual at
+# module scope too. tau_coding_agent.testing is therefore TUI-side as a whole --
+# testing/__init__.py re-exports render -- and needs this extra.
+tui = [
+    "textual>=0.47",
+    "rich",
+]
+# The session store. tau-jmfts is a separate distribution and stays that way; this
+# extra is only a convenience spelling for it. store_factory.py imports it lazily
+# and converts a missing package into a StoreError that names this extra, so
+# `--store jmfts` without it fails with an instruction rather than a traceback.
+jmfts = ["ffwf-tau-jmfts==0.9.2"]
+dev = [
+    "ffwf-tau-coding-agent[tui,jmfts]==0.9.2",
+    "pytest",
+    "pytest-asyncio",
+    "ruff",
+    # Pinned, unlike every other dev tool here. mypy has no "state your rule set"
+    # knob the way ruff does, so its findings move with its version: verified on
+    # this tree, 2.1.0 reports 0 errors and 2.3.1 reports 50 across 12 files.
+    # Those 50 look like real findings that a newer mypy got better at seeing --
+    # mostly no-any-return -- so they are scheduled, not suppressed: clearing
+    # them is its own pass, and until then the gate must mean the same thing in
+    # every clone. Raise this bound WITH that pass, never to make a hook go green.
+    "mypy==2.1.*",
+    # TUI visual inspection (see docs/textual-headless-testing.md):
+    #   textual-dev            -> `textual run --dev` live CSS editing, `textual console`
+    #   pytest-textual-snapshot -> SVG visual-regression tests
+    #   cairosvg               -> rasterize an exported SVG so a human can look at it
+    "textual-dev",
+    "pytest-textual-snapshot",
+    "cairosvg",
+]
+
+# The PUBLIC repository only. This tree has a second, private git remote whose
+# history is unfiltered; its hostname must never reach this file or a README,
+# because both are uploaded verbatim (pyproject.toml ships inside the sdist).
+# tests/test_packaging.py enforces that.
+[project.urls]
+Homepage = "https://ffwfrobotics.github.io/tau/"
+Documentation = "https://ffwfrobotics.github.io/tau/"
+Repository = "https://github.com/jmccardle/tau"
+Issues = "https://github.com/jmccardle/tau/issues"
+
+[build-system]
+requires = ["setuptools>=77.0.3", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.dynamic]
+version = { attr = "tau_coding_agent.__version__" }
+
+# Non-.py files the installed package reads at runtime. Both are load-bearing:
+# bootstrap_config() reads tau_default_config.json out of the installed package on
+# first run (without it, `pip install tau-coding-agent` ships a τ that dies with
+# FileNotFoundError before it can print a prompt), and Parley.CSS_PATH resolves
+# parley.tcss next to app.py (without it, the TUI raises on startup with no
+# stylesheet). Covered by tests/test_packaging.py.
+[tool.setuptools.package-data]
+tau_coding_agent = ["tau_default_config.json", "parley.tcss"]
+
+# Two names for one entry point, not a symlink. A wheel cannot portably express a
+# symlink, and pip generates each console script as an independent wrapper it owns
+# in its RECORD -- so two entries uninstall as cleanly as one, on Windows too.
+#
+# `tau` is the name to type. It is also the name PyPI cannot reserve: console
+# script names have no registry, and at least one active project (`tau-ai`, an
+# unrelated pi-style harness) already ships its own `tau`. In an environment
+# holding both, whichever installed last owns the name, silently.
+#
+# `ffwf-tau` is the name that cannot be taken. It is the fallback when `tau` is
+# not ours, and the stable name for scripts, systemd units and Dockerfiles, where
+# ergonomics do not matter and being the right program does.
+[project.scripts]
+tau = "tau_coding_agent.cli:main"
+ffwf-tau = "tau_coding_agent.cli:main"

ffwf_tau_coding_agent-0.9.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ffwf_tau_coding_agent-0.9.2/src/ffwf_tau_coding_agent.egg-info/PKG-INFO

@@ -0,0 +1,166 @@
+Metadata-Version: 2.4
+Name: ffwf-tau-coding-agent
+Version: 0.9.2
+Summary: τ-coding-agent: Interactive TUI (Textual) + CLI
+Author: Fight Fire with Fire Robotics, LLC
+License-Expression: MIT
+Project-URL: Homepage, https://ffwfrobotics.github.io/tau/
+Project-URL: Documentation, https://ffwfrobotics.github.io/tau/
+Project-URL: Repository, https://github.com/jmccardle/tau
+Project-URL: Issues, https://github.com/jmccardle/tau/issues
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: ffwf-tau-agent-core==0.9.2
+Provides-Extra: tui
+Requires-Dist: textual>=0.47; extra == "tui"
+Requires-Dist: rich; extra == "tui"
+Provides-Extra: jmfts
+Requires-Dist: ffwf-tau-jmfts==0.9.2; extra == "jmfts"
+Provides-Extra: dev
+Requires-Dist: ffwf-tau-coding-agent[jmfts,tui]==0.9.2; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy==2.1.*; extra == "dev"
+Requires-Dist: textual-dev; extra == "dev"
+Requires-Dist: pytest-textual-snapshot; extra == "dev"
+Requires-Dist: cairosvg; extra == "dev"
+Dynamic: license-file
+
+# ffwf-tau-coding-agent
+
+The interface of **Tau**, a programmable coding agent harness: the `tau`
+command, its Textual terminal UI, and the headless run paths behind `tau -p` and
+`tau --mode rpc`.
+
+Tau began as a Python port of the TypeScript project
+[pi-mono](https://github.com/badlogic/pi-mono), which is still read as the
+reference implementation when porting or debugging; it now diverges from pi
+deliberately in several places.
+
+## Install
+
+```bash
+pip install ffwf-tau-coding-agent            # headless: the CLI, `tau -p`, `--mode rpc`
+pip install 'ffwf-tau-coding-agent[tui]'     # add the interactive TUI
+```
+
+Python 3.11 or newer. Pulls in `ffwf-tau-agent-core`, and through it
+`ffwf-tau-llm`. Note the `ffwf-` prefix: `tau-llm` and `tau-ai` on PyPI are
+unrelated projects.
+
+| Extra | Adds | Needed for |
+|---|---|---|
+| `ffwf-tau-coding-agent[tui]` | `textual`, `rich` | the interactive TUI. `tau -p` runs a full turn without it |
+| `ffwf-tau-coding-agent[jmfts]` | `ffwf-tau-jmfts` | `--store jmfts` session storage |
+
+**The interface is an extra, not a base dependency.** A headless install is 15
+packages and 13 MB; adding `[tui]` makes it 27 packages and 31 MB. Both extras
+report their own absence — asking for the TUI or for `--store jmfts` without the
+matching extra fails with the install command you need, not a traceback.
+
+### Two names for one command
+
+The install puts **both `tau` and `ffwf-tau`** on your PATH. They are the same
+entry point, not a link: each is a wrapper pip owns and removes on uninstall.
+
+Type `tau`. PyPI reserves distribution names but not command names, and at least
+one unrelated project ships its own `tau`; in an environment holding both,
+whichever installed last owns the name and neither pip nor uv says a word.
+`ffwf-tau` cannot be taken, which makes it the right name inside scripts,
+systemd units, and Dockerfiles. If `tau --version` does not report τ,
+`ffwf-tau --version` will.
+
+## Run
+
+```bash
+tau                                 # interactive TUI
+tau -p "list the files here"        # headless: print a transcript, exit
+tau -p --mode json "..."            # headless: JSONL lifecycle events instead of text
+tau --mode rpc                      # drive τ as a subprocess over stdio (JSON-RPC 2.0)
+tau -e permission_gate.py           # load an extension from a path
+tau --help                          # the exact contract; treat this page as the stale one
+```
+
+`tau -p` and `tau --mode rpc` both write and resume real sessions under
+`~/.tau/sessions/`, so a headless run appears in the TUI's sidebar and can be
+picked up interactively later. `--no-session` means nothing is persisted.
+
+Flags worth knowing: `-m/--model`, `-t/--tools` and `-nt/--no-tools`,
+`-e/--extension PATH`, `--thinking {off,minimal,low,medium,high,xhigh}`,
+`-c/--continue`, `--session REF`, `--fork REF`, `--store {file,jmfts}`.
+
+## Configure
+
+On first run τ writes `~/.tau/config.json` from a default shipped inside the
+package. It holds the `models` map that `--model` resolves names against, plus
+per-extension config and the `session_store` block. A model entry names the
+provider, the base URL, and the context window, so pointing τ at a local
+OpenAI-compatible server (vLLM, llama.cpp, Ollama) is a config edit rather than
+a code change.
+
+## The TUI
+
+Built on [Textual](https://textual.textualize.io/). Streamed text renders at
+30 Hz; tool calls and their results appear as their own blocks.
+
+| Key | Action |
+|---|---|
+| `Ctrl+Enter` | send the message |
+| `Ctrl+B` | toggle the session sidebar |
+| `Ctrl+N` | new chat |
+| `Ctrl+G` | browse the conversation tree |
+| `Ctrl+Z` | roll back the last turn |
+| `Ctrl+R` / `Ctrl+T` | show or hide reasoning / tool blocks |
+| `Ctrl+E` | extensions |
+| `Ctrl+P` | command palette |
+| `Escape` | cancel the current generation |
+
+**The sidebar and the tree browser are two different things.** The sidebar picks
+*which session to open* — a flat list grouped by date. `Ctrl+G` opens a browser
+over the branch structure *inside the current conversation*, where you navigate
+to an earlier node, summarise a branch, or elide a span. Typed commands cover
+the rest: `/compact`, `/tree`, `/fork`, `/extensions`.
+
+## Why it is a separate package
+
+Everything here is presentation and process management. The agent lives in
+`ffwf-tau-agent-core`, which has no Textual dependency and never imports this
+package. `ffwf-tau-jmfts` is a peer rather than a dependency: `--store jmfts`
+imports it lazily and fails at startup if it is absent, never falling back to
+files without saying so.
+
+If you want the agent rather than the interface, use the runtime directly:
+
+```python
+import asyncio
+from tau_agent_core import create_agent_session
+
+
+async def main():
+    session = create_agent_session(model="gpt-4o", tools=["read", "bash"])
+    print(await session.prompt("What is in this directory?"))
+
+
+asyncio.run(main())
+```
+
+## Docs
+
+- `docs/tau-coding-agent.md` — design notes for this package.
+- `docs/CLI-PLAN.md` — the flag set and its status.
+- `docs/REMOTE-CONTROL.md`, `docs/RPC-PROTOCOL.md` — `--mode rpc`.
+- `docs/EXTENSIONS-WALKTHROUGH.md` — writing an extension to load with `-e`.
+
+Repository: <https://github.com/jmccardle/tau>
+
+## The rest of Tau
+
+| Distribution | Imports as | What it is |
+|---|---|---|
+| `ffwf-tau-llm` | `tau_llm` | the provider and streaming layer |
+| `ffwf-tau-agent-core` | `tau_agent_core` | the agent loop, tools, sessions, extensions |
+| `ffwf-tau-jmfts` | `tau_jmfts` | a JMFTS-backed session store |
+
+MIT © Fight Fire with Fire Robotics, LLC