tau-coding-agent 0.5.7__tar.gz → 0.6.1__tar.gz

{tau_coding_agent-0.5.7 → tau_coding_agent-0.6.1}/MANIFEST.in

@@ -2,3 +2,5 @@ recursive-include tau/builtins *
 recursive-include docs *
 include README.md
 include LICENSE
+global-exclude *.py[cod]
+global-exclude __pycache__

tau_coding_agent-0.6.1/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.4
+Name: tau-coding-agent
+Version: 0.6.1
+Summary: A self-extensible agent CLI with terminal UI, multi-provider LLM support, session management with branching, and a plugin system for tools and commands
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: anthropic==0.109.1
+Requires-Dist: certifi==2026.5.20
+Requires-Dist: click==8.4.1
+Requires-Dist: filelock==3.29.3
+Requires-Dist: google-genai==2.8.0
+Requires-Dist: httpx==0.28.1
+Requires-Dist: mistralai==2.4.9
+Requires-Dist: ollama==0.6.2
+Requires-Dist: openai==2.41.1
+Requires-Dist: packaging==26.2
+Requires-Dist: pillow==12.2.0
+Requires-Dist: pydantic==2.13.4
+Requires-Dist: python-dotenv==1.2.2
+Requires-Dist: uuid7==0.1.0
+Requires-Dist: websockets==16.0
+Requires-Dist: mistletoe==1.5.1
+Requires-Dist: pyyaml==6.0.2
+Requires-Dist: pygments==2.20.0
+Requires-Dist: pathspec==1.1.1
+Requires-Dist: posthog==7.21.3
+Requires-Dist: pylatexenc==2.10
+Requires-Dist: gitpython==3.1.50
+Requires-Dist: grapheme==0.6.0
+Requires-Dist: arrow==1.4.0
+Requires-Dist: kiwisolver==1.5.0
+Requires-Dist: tiktoken==0.13.0
+Provides-Extra: tools
+Requires-Dist: ripgrep>=14.0.0; extra == "tools"
+Requires-Dist: ast-grep-cli>=0.44.0; extra == "tools"
+Dynamic: license-file
+
+# Tau (τ)
+
+Tau is a Python agent framework and terminal coding assistant. It combines an
+interactive terminal UI, multiple model providers, persistent sessions, tool
+execution, and an extension system in one package.
+
+<p align="center">
+  <img src="assets/tui.jpeg" alt="Tau interactive terminal interface" width="700">
+</p>
+
+## Quick start
+
+Tau requires Python 3.12 or later.
+
+```bash
+pip install tau-coding-agent
+```
+
+Set a provider API key and start Tau:
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+tau
+```
+
+Google AI Studio works through the `google` provider:
+
+```bash
+export GOOGLE_API_KEY=...
+tau --model google/gemini-2.5-flash
+```
+
+You can also run `/login` inside Tau to save provider credentials.
+
+Then ask Tau to work in the current directory:
+
+```text
+Explain this repository, run its tests, and fix any failures.
+```
+
+## Common workflows
+
+```bash
+tau                                      # Start an interactive session
+tau --resume                             # Resume the latest session
+tau --model claude-sonnet-4-6            # Start with a specific model
+tau --print "Summarize this repository"  # Run once and print the result
+tau --mode json "Summarize this repo"    # Emit structured JSON events
+tau --mode rpc                           # Start JSON-RPC mode for IDE clients
+```
+
+Inside an interactive session:
+
+```text
+/model       Choose a model
+/resume      Resume another session
+/tree        Navigate session branches
+/compact     Compact a long conversation
+/theme       Change the terminal theme
+/login       Save provider credentials
+/help        Show commands and shortcuts
+```
+
+See the [CLI reference](docs/cli-reference.md) for every option and command.
+
+## What Tau provides
+
+- **Interactive terminal UI** with multiline editing, searchable pickers,
+  syntax highlighting, Markdown, and terminal-readable LaTeX math.
+- **Multiple model providers**, including Anthropic, OpenAI, Google Gemini,
+  Mistral, Ollama, Groq, xAI, Bedrock, OpenRouter, and others.
+- **Persistent session trees** with resume, fork, clone, branch navigation,
+  summarization, and automatic context compaction.
+- **Built-in tools** for terminal commands, file operations, globbing, and
+  search. Long-running terminal commands stream into one persistent output
+  block.
+- **Media support** for images, audio, video, and text files through file
+  references, clipboard input, and the Python API.
+- **Speech APIs** for text-to-speech and speech-to-text, including word or
+  segment timestamps when supported by the selected provider.
+- **Extensibility** through custom tools, slash commands, hooks, themes,
+  skills, prompts, and in-memory Python extensions.
+- **Embedding and integration** through the Python API, JSON event mode, and
+  bidirectional JSON-RPC.
+
+## Referencing files
+
+Type `@` in the interactive editor to search for a project file:
+
+```text
+Review @src/service.py and add tests for its error handling.
+```
+
+For one-shot execution, attach a file explicitly:
+
+```bash
+tau --print --prompt "Explain this file" --file src/service.py
+```
+
+Tau also discovers project instructions from `AGENTS.md` and `CLAUDE.md`.
+See [Project Context Files](docs/project-context.md) for trust and discovery
+behavior.
+
+## Authentication and configuration
+
+Tau resolves provider credentials in this order:
+
+1. A programmatic runtime override
+2. A credential saved in `~/.tau/auth.json` (including keys saved by `/login`)
+3. A provider environment variable such as `ANTHROPIC_API_KEY`,
+   `OPENAI_API_KEY`, and `GOOGLE_API_KEY`
+
+Settings are merged in this order:
+
+1. Built-in defaults
+2. `~/.tau/settings.json`
+3. `.tau/settings.json`
+4. Environment variables
+5. Command-line options
+
+See [Authentication](docs/auth.md), [Installation](docs/installation.md), and
+[Inference Providers](docs/inference-providers.md) for provider-specific
+setup.
+
+## Documentation
+
+- [Quickstart](docs/quickstart.md) — First session in five minutes
+- [Usage](docs/usage.md) — Interactive workflows and commands
+- [CLI Reference](docs/cli-reference.md) — Command-line options and modes
+- [Inference Providers](docs/inference-providers.md) — Providers and speech timestamps
+- [Sessions](docs/sessions.md) — Persistence, branching, and compaction
+- [Tools](docs/tools.md) — Built-in and custom tools
+- [Extensions](docs/extensions.md) — Tools, commands, hooks, and plugins
+- [Terminal UI](docs/tui.md) — Rendering, Markdown, math, and components
+- [Python API](docs/python-api.md) — Embed Tau in another application
+- [Architecture](docs/architecture.md) — Internal design and data flow
+
+The complete documentation index is available at [docs/index.md](docs/index.md).
+
+## Install from source
+
+```bash
+git clone https://github.com/Jeomon/Tau.git
+cd Tau
+pip install -e .
+tau
+```
+
+## Security
+
+Tau executes enabled tools with the operating-system permissions of the process
+that launched it. Review project instructions and commands before approving
+work in untrusted repositories. Use a container or external sandbox when
+stronger isolation is required.
+
+Dependency versions are pinned and recorded in `uv.lock`. See
+[SECURITY.md](SECURITY.md) for vulnerability reporting and supply-chain
+practices.
+
+## Development
+
+```bash
+mypy tau/
+pyright tau/
+ruff check tau/
+ruff format tau/
+python -m pytest
+```
+
+See [Development Setup](docs/development.md) and
+[Contributing](CONTRIBUTING.md).
+
+## License
+
+Tau is licensed under the [MIT License](LICENSE).

tau_coding_agent-0.6.1/README.md

@@ -0,0 +1,175 @@
+# Tau (τ)
+
+Tau is a Python agent framework and terminal coding assistant. It combines an
+interactive terminal UI, multiple model providers, persistent sessions, tool
+execution, and an extension system in one package.
+
+<p align="center">
+  <img src="assets/tui.jpeg" alt="Tau interactive terminal interface" width="700">
+</p>
+
+## Quick start
+
+Tau requires Python 3.12 or later.
+
+```bash
+pip install tau-coding-agent
+```
+
+Set a provider API key and start Tau:
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+tau
+```
+
+Google AI Studio works through the `google` provider:
+
+```bash
+export GOOGLE_API_KEY=...
+tau --model google/gemini-2.5-flash
+```
+
+You can also run `/login` inside Tau to save provider credentials.
+
+Then ask Tau to work in the current directory:
+
+```text
+Explain this repository, run its tests, and fix any failures.
+```
+
+## Common workflows
+
+```bash
+tau                                      # Start an interactive session
+tau --resume                             # Resume the latest session
+tau --model claude-sonnet-4-6            # Start with a specific model
+tau --print "Summarize this repository"  # Run once and print the result
+tau --mode json "Summarize this repo"    # Emit structured JSON events
+tau --mode rpc                           # Start JSON-RPC mode for IDE clients
+```
+
+Inside an interactive session:
+
+```text
+/model       Choose a model
+/resume      Resume another session
+/tree        Navigate session branches
+/compact     Compact a long conversation
+/theme       Change the terminal theme
+/login       Save provider credentials
+/help        Show commands and shortcuts
+```
+
+See the [CLI reference](docs/cli-reference.md) for every option and command.
+
+## What Tau provides
+
+- **Interactive terminal UI** with multiline editing, searchable pickers,
+  syntax highlighting, Markdown, and terminal-readable LaTeX math.
+- **Multiple model providers**, including Anthropic, OpenAI, Google Gemini,
+  Mistral, Ollama, Groq, xAI, Bedrock, OpenRouter, and others.
+- **Persistent session trees** with resume, fork, clone, branch navigation,
+  summarization, and automatic context compaction.
+- **Built-in tools** for terminal commands, file operations, globbing, and
+  search. Long-running terminal commands stream into one persistent output
+  block.
+- **Media support** for images, audio, video, and text files through file
+  references, clipboard input, and the Python API.
+- **Speech APIs** for text-to-speech and speech-to-text, including word or
+  segment timestamps when supported by the selected provider.
+- **Extensibility** through custom tools, slash commands, hooks, themes,
+  skills, prompts, and in-memory Python extensions.
+- **Embedding and integration** through the Python API, JSON event mode, and
+  bidirectional JSON-RPC.
+
+## Referencing files
+
+Type `@` in the interactive editor to search for a project file:
+
+```text
+Review @src/service.py and add tests for its error handling.
+```
+
+For one-shot execution, attach a file explicitly:
+
+```bash
+tau --print --prompt "Explain this file" --file src/service.py
+```
+
+Tau also discovers project instructions from `AGENTS.md` and `CLAUDE.md`.
+See [Project Context Files](docs/project-context.md) for trust and discovery
+behavior.
+
+## Authentication and configuration
+
+Tau resolves provider credentials in this order:
+
+1. A programmatic runtime override
+2. A credential saved in `~/.tau/auth.json` (including keys saved by `/login`)
+3. A provider environment variable such as `ANTHROPIC_API_KEY`,
+   `OPENAI_API_KEY`, and `GOOGLE_API_KEY`
+
+Settings are merged in this order:
+
+1. Built-in defaults
+2. `~/.tau/settings.json`
+3. `.tau/settings.json`
+4. Environment variables
+5. Command-line options
+
+See [Authentication](docs/auth.md), [Installation](docs/installation.md), and
+[Inference Providers](docs/inference-providers.md) for provider-specific
+setup.
+
+## Documentation
+
+- [Quickstart](docs/quickstart.md) — First session in five minutes
+- [Usage](docs/usage.md) — Interactive workflows and commands
+- [CLI Reference](docs/cli-reference.md) — Command-line options and modes
+- [Inference Providers](docs/inference-providers.md) — Providers and speech timestamps
+- [Sessions](docs/sessions.md) — Persistence, branching, and compaction
+- [Tools](docs/tools.md) — Built-in and custom tools
+- [Extensions](docs/extensions.md) — Tools, commands, hooks, and plugins
+- [Terminal UI](docs/tui.md) — Rendering, Markdown, math, and components
+- [Python API](docs/python-api.md) — Embed Tau in another application
+- [Architecture](docs/architecture.md) — Internal design and data flow
+
+The complete documentation index is available at [docs/index.md](docs/index.md).
+
+## Install from source
+
+```bash
+git clone https://github.com/Jeomon/Tau.git
+cd Tau
+pip install -e .
+tau
+```
+
+## Security
+
+Tau executes enabled tools with the operating-system permissions of the process
+that launched it. Review project instructions and commands before approving
+work in untrusted repositories. Use a container or external sandbox when
+stronger isolation is required.
+
+Dependency versions are pinned and recorded in `uv.lock`. See
+[SECURITY.md](SECURITY.md) for vulnerability reporting and supply-chain
+practices.
+
+## Development
+
+```bash
+mypy tau/
+pyright tau/
+ruff check tau/
+ruff format tau/
+python -m pytest
+```
+
+See [Development Setup](docs/development.md) and
+[Contributing](CONTRIBUTING.md).
+
+## License
+
+Tau is licensed under the [MIT License](LICENSE).

{tau_coding_agent-0.5.7 → tau_coding_agent-0.6.1}/docs/inference-providers.md

@@ -60,7 +60,9 @@ tau --model openai/gpt-4o -p "Say hello"
 
 ## Google Gemini
 
-Google provides Gemini models with multimodal capabilities.
+Google AI Studio provides API-key access to Gemini models through the Google
+Gen AI SDK. Tau's `google` provider uses the Gemini Developer API; it is
+separate from the `google-vertex` provider, which uses Google Cloud.
 
 ### Setup
 
@@ -75,9 +77,16 @@ export GOOGLE_API_KEY=...
 ### Verify
 
 ```bash
-tau --model google/gemini-2.0-flash -p "Say hello"
+tau --model google/gemini-2.5-flash -p "Say hello"
 ```
 
+Current Google AI Studio model IDs include:
+
+- `gemini-3.5-flash` (stable)
+- `gemini-3.1-flash-lite` (stable)
+- `gemini-3.1-pro-preview` (preview)
+- `gemini-2.5-pro`, `gemini-2.5-flash`, and `gemini-2.5-flash-lite`
+
 ## Mistral AI
 
 Mistral offers efficient open-source-based models.
@@ -152,6 +161,17 @@ tau --model ollama/mistral -p "Say hello"
 
 ## Switching Providers
 
+## Speech-to-Text Timestamps
+
+Pass `TimestampGranularity.Word` or `TimestampGranularity.Segment` in
+`STTContext.timestamp_granularities` when using the Python API.
+
+- OpenAI `whisper-1` and Groq Whisper models support word and segment timestamps.
+- OpenAI GPT-4o transcription models return plain JSON and do not expose detailed
+  timestamps through this API.
+- ElevenLabs Scribe and Sarvam Saaras support word timestamps. Sarvam receives
+  `with_timestamps=true` when word timestamps are requested.
+
 ### Command Line
 
 Use a specific provider for a single session:

{tau_coding_agent-0.5.7 → tau_coding_agent-0.6.1}/docs/installation.md

@@ -61,9 +61,12 @@ Get your API key from [OpenAI's platform](https://platform.openai.com/account/ap
 
 ```bash
 export GOOGLE_API_KEY=...
+tau --model google/gemini-2.5-flash
 ```
 
-Create a key at [Google AI Studio](https://aistudio.google.com).
+Create a key at [Google AI Studio](https://aistudio.google.com). The `google`
+provider uses the Gemini Developer API and is separate from the Google Vertex
+AI provider.
 
 ### Mistral AI
 
@@ -144,7 +147,7 @@ When you start Tau, it will load your models. Press `/model` to see all availabl
 To remove Tau:
 
 ```bash
-pip uninstall tau
+pip uninstall tau-coding-agent
 ```
 
 This removes the tau command but leaves configuration and session data in `~/.tau/`.

{tau_coding_agent-0.5.7 → tau_coding_agent-0.6.1}/docs/python-api.md

@@ -325,6 +325,9 @@ await runtime.execute_terminal("git status")
 | `runtime.settings_manager` | `SettingsManager` | Settings access |
 | `runtime.extension_runtime` | `ExtensionRuntime \| None` | Loaded extensions |
 
+`ExtensionRuntime.get_extensions()` returns the loaded extensions in
+registration order as a read-only tuple.
+
 ## Listening to Events
 
 Subscribe to the hook bus directly to observe what the agent does:

{tau_coding_agent-0.5.7 → tau_coding_agent-0.6.1}/docs/quickstart.md

@@ -33,6 +33,7 @@ export OPENAI_API_KEY=sk-...
 
 ```bash
 export GOOGLE_API_KEY=...
+tau --model google/gemini-2.5-flash
 ```
 
 ### Other Providers
@@ -66,6 +67,10 @@ Summarize this repository and tell me how to run its checks.
 
 The agent will read files, run commands, and respond with a summary.
 
+Markdown responses support terminal-readable inline and display LaTeX math.
+Long-running terminal tools update their existing output block while streaming
+instead of printing a new block for every chunk.
+
 ### Media Support
 
 Tau can process multiple file types. Reference them with `@` during input:

{tau_coding_agent-0.5.7 → tau_coding_agent-0.6.1}/docs/sessions.md

@@ -63,6 +63,9 @@ Or the short form:
 tau -r
 ```
 
+After resuming, `/new` always starts an empty session; the startup resume
+selection is not reused for later session changes.
+
 ### Browse Sessions
 
 Choose from a list of previous sessions interactively:

{tau_coding_agent-0.5.7 → tau_coding_agent-0.6.1}/docs/themes.md

@@ -39,6 +39,8 @@ Set your default theme in `~/.tau/settings.json` or `.tau/settings.json`:
 ```
 
 Opens an interactive picker. Use ↑↓ to preview, Enter to apply.
+The theme submenu in `/settings` uses the same ↑/↓ live preview. Press Enter to
+apply or Escape to restore the previous theme.
 
 ---
 

{tau_coding_agent-0.5.7 → tau_coding_agent-0.6.1}/docs/tools.md

@@ -10,8 +10,8 @@ Tau ships with seven built-in tools covering file I/O, search, and shell executi
 
 Read a UTF-8 text file. Invalid byte sequences are replaced during decoding.
 Every returned line is prefixed with a content-based hashline anchor in the form
-`<line>:<hash>|<content>`. Duplicate content, including blank lines, can share a
-hash; the line number acts as a proximity hint when `edit` resolves an anchor.
+`<line>:<hash>|<content>`. Duplicate content, including blank lines, receives
+distinct anchors so `edit` can target the exact displayed line.
 
 | Parameter | Type | Required | Default | Description |
 |-----------|------|----------|---------|-------------|
@@ -37,6 +37,8 @@ used as a proximity hint and the closest occurrence is selected. An empty
 `new_content` deletes the selected range. Because the complete file is rewritten,
 an edit may normalize line endings. Edit-result diffs also display hashline anchors:
 removed lines use their old hashes, while added and context lines use current hashes.
+If an anchor hash is stale or invalid, the model-visible error includes current
+nearby hashline-anchored file content and asks the agent to re-read before retrying.
 Edit diffs always show every changed line. By default they include three unchanged
 lines around each change and collapse larger unchanged gaps into `… (+N lines)`;
 Ctrl+O expands those gaps to show the complete file context.
@@ -64,9 +66,11 @@ Commands run in the agent's current working directory.
 
 Output is streamed through tool-update events while the command runs. Updates
 are throttled to at most once every 100 milliseconds, with guaranteed initial
-and final updates. Timeout and cancellation terminate the command's complete
-process tree. Programs may still buffer their own output; use an unbuffered mode
-such as `python -u` when immediate output is required.
+and final updates. The interactive TUI refreshes the existing result block for
+each update; when a long result is collapsed, its newest lines remain visible
+while the command is running. Timeout and cancellation terminate the command's
+complete process tree. Programs may still buffer their own output; use an
+unbuffered mode such as `python -u` when immediate output is required.
 
 ### glob
 

{tau_coding_agent-0.5.7 → tau_coding_agent-0.6.1}/docs/tui.md

@@ -32,6 +32,14 @@ from tau.tui import (
 | Overlays | `OverlayOptions`, `OverlayHandle` |
 | Styling | Theme dataclasses, color helpers, `render_markdown` |
 
+### Markdown math
+
+`render_markdown` converts inline (`$...$`) and display (`$$...$$`) LaTeX math
+to terminal-readable Unicode text through `pylatexenc`. Display math is placed
+on separate lines. Code spans and fenced code blocks retain their original
+LaTeX source. This is a readable plain-text representation, not fully typeset
+mathematical layout.
+
 ## Minimal Application
 
 ```python
@@ -78,15 +86,17 @@ automatically during shutdown.
 Subclass `Component` to create a reusable view:
 
 ```python
-from tau.tui import Component, KeyEvent
+from tau.tui import Buffer, Component, KeyEvent, Line, Rect, Span
 
 
 class Counter(Component):
     def __init__(self) -> None:
         self.value = 0
 
-    def render(self, width: int) -> list[str]:
-        return [f"Count: {self.value}"[:width]]
+    def render_cells(self, area: Rect, buf: Buffer) -> int:
+        buf.grow_to(area.y + 1)
+        buf.set_line(area.x, area.y, Line([Span(f"Count: {self.value}")]), area.width)
+        return 1
 
     def handle_input(self, event: object) -> bool:
         if isinstance(event, KeyEvent) and event.matches("up"):
@@ -95,8 +105,9 @@ class Counter(Component):
         return False
 ```
 
-`render()` returns one string per terminal row. Components must respect the
-provided width and must not include newline characters inside a returned line.
+`render_cells()` writes styled cells into the provided `Buffer` and returns the
+number of rows written. Components must grow dynamic buffers before writing and
+must respect the provided `Rect`.
 
 ## Layout
 
@@ -106,6 +117,8 @@ provided width and must not include newline characters inside a returned line.
 - `Columns` creates multi-line fixed and flexible columns.
 - `Rows` distributes a fixed terminal height across children.
 - `Constrained` places a child at an absolute or percentage width.
+- `Box` wraps a child `Component` with horizontal/vertical padding and an
+  optional background `Style`.
 
 ## Focus and Input
 
@@ -166,7 +179,8 @@ Runtime-aware behavior belongs in `tau.modes.interactive`.
 
 This boundary is enforced by `tests/test_tui_public_api.py`.
 
-The renderer retains only the current transcript frame and its current
-line-wrapping cache. Unchanged lines reuse width calculations across frames so
-streaming updates do not repeatedly parse ANSI styling across the complete
-session.
+The renderer retains only the current transcript frame. Styled content that
+exceeds its available width wraps directly into Buffer rows without losing
+content, and reflows when the terminal is resized. Finalized message rows are
+cached as cells so streaming updates do not repeatedly parse ANSI styling
+across the complete session.

{tau_coding_agent-0.5.7 → tau_coding_agent-0.6.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tau-coding-agent"
-version = "0.5.7"
+version = "0.6.1"
 description = "A self-extensible agent CLI with terminal UI, multi-provider LLM support, session management with branching, and a plugin system for tools and commands"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -29,9 +29,12 @@ dependencies = [
     "pygments==2.20.0",
     "pathspec==1.1.1",
     "posthog==7.21.3",
+    "pylatexenc==2.10",
     "gitpython==3.1.50",
     "grapheme==0.6.0",
     "arrow==1.4.0",
+    "kiwisolver==1.5.0",
+    "tiktoken==0.13.0",
 ]
 
 [project.scripts]

{tau_coding_agent-0.5.7 → tau_coding_agent-0.6.1}/tau/agent/prompt/builder.py

@@ -146,6 +146,18 @@ _GENERAL_GUIDELINES = [
         "Prioritize accuracy over agreement — investigate before confirming, and "
         "disagree when the evidence calls for it."
     ),
+    (
+        "Verify before reporting a task done: run the tests, build, or command that "
+        "exercises the change. Don't present untested, partial, or stubbed-out work as complete."
+    ),
+    (
+        "When fixing a bug, reproduce it before changing code. If the same fix attempt "
+        "fails twice, stop and investigate the root cause instead of retrying it."
+    ),
+    (
+        "Treat git history as shared: never force-push, amend a commit that isn't yours, "
+        "or skip hooks (--no-verify) without the user's explicit go-ahead."
+    ),
 ]
 
 _PRECEDENCE_GUIDELINES = """\