Metadata-Version: 2.4
Name: jaato-tui
Version: 0.4.3
Summary: Jaato TUI - Terminal user interface for jaato server
Author: apanoia
License-Expression: BUSL-1.1
Project-URL: Repository, https://github.com/Jaato-framework-and-examples/jaato
Project-URL: Issues, https://github.com/Jaato-framework-and-examples/jaato/issues
Keywords: jaato,tui,terminal,client
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: jaato-sdk
Requires-Dist: prompt_toolkit>=3.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: python-dotenv
Requires-Dist: pyte>=0.8.0
Requires-Dist: wcwidth
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Provides-Extra: vision
Requires-Dist: cairosvg>=2.7.0; extra == "vision"
Provides-Extra: all
Requires-Dist: jaato-tui[dev,vision]; extra == "all"

# Changelog

## 0.4.3 (2026-09-09)

- ci: publish to PyPI, and add jaato-eval to the release set (#923)
- feat(media): deliver binary media chunks, and know when a spoken turn ended (#824)
- chore: normalise line endings to LF, once, in one commit (#794) (#807)
- fix(tui,permission): make a permission prompt readable, and answerable only as chosen (#796)
- fix(tui,clarification): answer a batched clarification instead of hanging (#704) (#783)
- fix(providers): one prompt-token convention, converted at the seam (#758) (#763)
- fix(security): close the symlink escapes in file tools and search (#669) (#746)
- fix(daemon): refuse a relative path at the process boundary (#742) (#744)
- test(guards): a guard that cannot detect its own reversion now fails the build (#665)
- fix(memory): list_memory_tags reported an empty store while holding a raw queue (#664)
- fix(sdk): the breaking change needs a version that says so (#636)
- feat(sdk)!: create_session says which failure happened (#635)
- Thread spend_total_tokens to the client (UsageBreakdown)
- telemetry: emit user.id for Langfuse User Tracking
- telemetry: propagate session.id to child spans for Langfuse best practices
- telemetry: pricing-table cost on spans + dedicated Langfuse backend
- telemetry: stamp provider cost on LLM spans + OTLP protocol selection for Langfuse
- feat(reliability): compute is_error_result on tool.call_completed
- feat(tui): render human template names in tool tree (post-#136 follow-up) (#137)
- tui 0.4.2: pass client_type through to IPCRecoveryClient (SDK 0.12.0 compat)
- tui 0.4.1: restore Ctrl+B (toggle budget panel) keybinding
- tui 0.4.0: minor bump for reconnect helper print
- tui: print reconnect helper to terminal after detach
- tui: fix crash on multi-wave tool finalization (TypeError None - int)
- release: coordinated bump for gap 1-5 SDK release
- sdks: protocol-version compat (gap 5)
- sdks: subscribe API, profile picker, inline session spec, cost/usage refactor
- openers: action-dict shape with raw/diff actions and fallthrough
- Fix TUI startup crash: invalid 's-h' keybinding rejected by prompt_toolkit
- SDK + TUI parity: end_session / delete_session typed methods
- Add hide / show-hidden / gitignore-toggle bindings to the workspace panel
- SDK helpers: compute_cache_hit_percent + TUI adoption
- Add workspace panel keybinding to paste selection as @reference
- Add per-extension openers for workspace panel "open file" action
- TUI j-table: render at OutputBuffer width, not Rich's default 80
- Render <j-code>/<j-table> in the TUI; drop per-client branching on the server
- References: knowledge bundles with per-bundle sidecars + reconcile
- References: move sidecar row ordering to embedding_config.json
- Cache hit rate: divide by total input, not just new (uncached) input
- signal_completion: typed payloads from profile-declared schema
- template: rename writeFileFromTemplate → renderTemplateToFile
- Fix: remove stale icon_lines reference that crashed TUI event handler
- Bundle tool_id_mappings in SessionInfoEvent for guaranteed delivery
- ToolIdRegistryEvent: server pushes ID→name mapping to clients
- TUI: resolve hash-derived tool/category IDs in argument display
- Complete agent/profile split: SDK, TUI, and deprecation warning
- Remove gen-references profile from example directory
- Remove gen-references prompt template
- Rewrite gen-references profile and prompt for full catalog generation
- Add gen-references profile and prompt template
- Fix completed step results lost on plan structural changes
- Unify EventBus as single internal event backbone

---

# Rich Client

Interactive TUI client for jaato with multi-agent support, streaming output, and rich formatting.

## Installation

```bash
pip install jaato-tui
```

## Overview

The rich client provides:
- Multi-agent conversation view with agent cycling
- Streaming output with real-time rendering
- Permission prompts for tool execution
- Plan panel for tracking agent plans
- Customizable keybindings and themes

## Running

```bash
# Start server daemon first
.venv/bin/python -m server --ipc-socket /tmp/jaato.sock --daemon

# Connect TUI to running server
.venv/bin/python jaato-tui/rich_client.py --connect /tmp/jaato.sock
```

## Commands

### General

| Command | Description |
|---------|-------------|
| `help` | Show help message and available commands |
| `reset` | Clear conversation history |
| `history` | Show full conversation history |
| `context` | Show context window usage |
| `export [file]` | Export session to YAML |
| `clear` | Clear output panel |
| `quit` / `exit` | Exit the client |

### Model

| Command | Description |
|---------|-------------|
| `model <name>` | Switch to a different model |

### Tools

| Command | Description |
|---------|-------------|
| `tools` | Manage tools available to the model |
| `tools list` | List all tools with enabled/disabled status |
| `tools enable <name>` | Enable a tool (or `all`) |
| `tools disable <name>` | Disable a tool (or `all`) |

### Plugins

| Command | Description |
|---------|-------------|
| `plugins` | List available plugins with status |

### Sessions

| Command | Description |
|---------|-------------|
| `save [name]` | Save current session |
| `resume [name]` | Resume a saved session |
| `sessions` | List saved sessions |

### Plan

| Command | Description |
|---------|-------------|
| `plan` | Show current plan status |

### Screenshot

Capture TUI state as images. The command is intercepted client-side. By default, a system hint is sent to the model with the capture path.

| Command | Description |
|---------|-------------|
| `screenshot` | Capture and send hint to model |
| `screenshot nosend` | Capture only, no hint to model |
| `screenshot format F` | Set output format (svg, png, html) |
| `screenshot auto` | Toggle auto-capture on turn end |
| `screenshot interval N` | Capture every N ms during streaming (0=off) |
| `screenshot help` | Show help |

Captures are saved to `/tmp/jaato_vision/` by default. SVG is the default format. PNG requires `cairosvg` package.

### Keybindings

| Command | Description |
|---------|-------------|
| `keybindings` | Manage keyboard shortcuts |
| `keybindings list` | Show current keybinding configuration |
| `keybindings set <action> <key>` | Set a keybinding |
| `keybindings profile` | Show/switch terminal-specific profiles |
| `keybindings reload` | Reload keybindings from config files |

### Authentication

**Anthropic Claude:**

| Command | Description |
|---------|-------------|
| `anthropic-auth login` | Open browser for OAuth authentication |
| `anthropic-auth code <code>` | Complete login with authorization code |
| `anthropic-auth logout` | Clear stored OAuth tokens |
| `anthropic-auth status` | Show current authentication status |

**Antigravity (Google IDE Backend):**

| Command | Description |
|---------|-------------|
| `antigravity-auth login` | Open browser for Google OAuth |
| `antigravity-auth code <code>` | Complete login with authorization code |
| `antigravity-auth logout` | Clear stored accounts |
| `antigravity-auth status` | Show current authentication status |
| `antigravity-auth accounts` | List all authenticated accounts |

### Theme

| Command | Description |
|---------|-------------|
| `theme` | Show current theme info |
| `theme <name>` | Switch theme (dark, light, high-contrast, dracula, or custom) |
| `theme reload` | Reload from config files |

## Default Keybindings

| Action | Key | Description |
|--------|-----|-------------|
| Submit | `Enter` | Send message |
| Newline | `Escape` `Enter` | Insert newline |
| Clear input | `Escape` `Escape` | Clear input buffer |
| Cancel | `Ctrl-C` | Cancel current operation |
| Exit | `Ctrl-D` | Exit the client |
| Scroll up | `PageUp` | Scroll output up |
| Scroll down | `PageDown` | Scroll output down |
| Scroll top | `Home` | Scroll to top |
| Scroll bottom | `End` | Scroll to bottom |
| Toggle plan | `Ctrl-P` | Show/hide plan panel |
| Toggle tools | `Ctrl-T` | Show/hide tools panel |
| Cycle agents | `Ctrl-A` | Cycle through agents |
| Yank/copy | `Ctrl-Y` | Copy to clipboard |
| View full | `V` | View full content in pager |

## Configuration

### Keybindings

Keybindings can be configured via:
1. Project config: `.jaato/keybindings.json`
2. User config: `~/.jaato/keybindings.json`
3. Environment variables: `JAATO_KEY_<ACTION>=<key>`

Priority: Environment variables > Project config > User config > Defaults

### Themes

The rich client supports customizable themes with automatic persistence.

**Built-in Themes:**

| Theme | Description |
|-------|-------------|
| `dark` | Dark background with cyan/green accents (default) |
| `light` | Light background for bright terminals |
| `high-contrast` | High contrast for accessibility |

Custom themes can be defined in:
- Project: `.jaato/theme.json`
- User: `~/.jaato/theme.json`

Theme selection is persisted to `~/.jaato/preferences.json`.

**Custom Theme Example:**

```json
{
  "name": "my-theme",
  "version": "1.0",
  "colors": {
    "primary": "#5fd7ff",
    "secondary": "#87d787",
    "success": "#5fd75f",
    "warning": "#ffff5f",
    "error": "#ff5f5f",
    "muted": "#808080",
    "background": "#1a1a1a",
    "surface": "#333333",
    "text": "#ffffff",
    "text_muted": "#aaaaaa"
  }
}
```

## Environment Variables

| Variable | Purpose |
|----------|---------|
| `JAATO_THEME` | Override theme (temporary) |
| `JAATO_VISION_DIR` | Screenshot output directory (default: `/tmp/jaato_vision`) |
| `JAATO_VISION_FORMAT` | Screenshot format: `svg` (default), `png`, `html` |
| `JAATO_COPY_MECHANISM` | Clipboard provider: `osc52` (default) |
| `JAATO_COPY_SOURCES` | Sources to copy: `model` (default), or `model&user&tool` |

## File References

Reference files in prompts with `@` prefix:

```
What's in @screenshot.png?
Review @src/main.py
```

## Related

- [Vision Capture Plugin](../shared/plugins/vision_capture/README.md) - Screenshot implementation
- [Architecture](../docs/architecture.md) - Framework architecture
