Agent Terminal UI
The terminal frontend for Arbora agent sessions.
Textual-based TUI connecting to an Arbora-served agent backend through a normalized ACP transport adapter.
Documentation · Architecture · Features · Configuration
Overview
Agent Terminal UI is a Textual-based terminal interface
for interacting with agents served by Arbora.
It connects to an Arbora-hosted agent-utilities backend through a normalized transport
adapter; the currently shipped adapter uses ACP (JSON-RPC + SSE).
Key Capabilities
- Dual-protocol chat with a dynamic workflow sidebar discovered from live sideband events.
- Durable, crash-recoverable sessions: checkpoints, fork/resume, offline queueing, and archives.
- Workspace snapshots and rollback, reasoning-effort tiers, and multi-tier context compaction.
- A durable background task queue, lifecycle hooks, desktop notifications, and a governed tool-approval and workspace-trust model.
- A live capability palette and run Mission Control over the Arbora gateway catalog.
The full command, keyboard shortcut, and module reference lives in Features below and in the official documentation.
Features
Core Functionality
- Normalized protocol adapter -- ACP JSON-RPC + SSE events are translated into one UI event vocabulary for interactive and headless clients
- Dynamic workflow sidebar -- discovers graph nodes from sideband events at runtime; nodes are never hardcoded
- Phase labels -- Planning, Discovery, Execution, Validation
- Completed node markers -- checkmarks on finished specialists
- Rich tool execution display -- extensible formatter system for rendering tool calls and results
- Human-in-the-loop tool approval -- modal for confirming sensitive tool calls before execution
- Multi-modal image attachment -- attach images to messages for visual reasoning
- Session management and chat history -- browse and resume previous conversations
- MCP server browser -- inspect connected MCP servers and their tools
- Live capability palette -- search the gateway catalog from Alt+C, the global command palette, the sidebar, or
/capabilities; forms are generated from action schemas - Governed generic invocation -- every action is preflighted, acknowledged as a canonical run, followed through events, and safely resumed when approval is pending
- Live run Mission Control --
/rundiscovers recent runs and follows versioned events by cursor, with sequence deduplication and bounded-history gap notices
Session Persistence & Crash Recovery (TUI-1)
- SQLite-backed sessions -- durable session storage at
~/.local/share/agent-utilities/agent_terminal_ui.db(override the directory withAGENT_UTILITIES_DATA_DIR) - Pre-turn checkpointing -- automatic checkpoints before each turn for crash recovery
- Session fork/resume -- fork sessions at any turn number with
fork_session() - Offline queue -- messages queued during disconnection survive process restarts
- Session archive -- archive, search, and filter sessions by status
Workspace Snapshots & Rollback (TUI-2)
- Side-git snapshots -- pre/post-turn workspace snapshots without touching your
.git - Snapshot restore --
/restore Nto roll back workspace to any previous turn - Diff viewer -- view changes between snapshot points
- Auto-pruning -- snapshots older than configurable max age are cleaned up
Reasoning Effort Tiers & Auto Routing (TUI-3)
- Three-tier reasoning -- OFF / HIGH / MAX with
Shift+Tabcycling - Auto model routing -- lightweight heuristic selects optimal model and thinking level per turn
- Mode-aware defaults -- plan/code modes default to higher reasoning
Context Compaction Engine (TUI-4)
- Multi-tier compaction -- L1 (summarize tools), L2 (summarize old turns), L3 (drop old), Cycle (hard reset)
- Configurable thresholds -- token-based triggers at 192k/384k/576k/768k
- Auto-compact toggle -- automatic compaction when context window pressure is detected
- Manual
/compact-- force compaction at any tier
Durable Task Queue (TUI-5)
- SQLite-backed tasks -- background tasks survive process restarts
- Bounded concurrency -- configurable maximum concurrent tasks
- Timeline events -- full event log per task (created, started, progress, completed/failed)
- Checklist tracking -- structured checklist state per task
- Crash recovery -- interrupted tasks are automatically marked as failed on restart
Lifecycle Hooks (TUI-6)
- TOML-configured hooks -- shell commands triggered on lifecycle events
- Supported events --
session_start,session_end,message_submit,tool_call_before/after,mode_change,on_error,shell_env - Timeout protection -- hooks are killed after configurable timeout
- Conditional triggers -- hooks can fire only for specific tool categories or modes
- Shell env injection --
shell_envhooks inject environment variables into tool execution
Desktop Notifications (TUI-7)
- OSC 9 / BEL notifications -- terminal-native notifications on long-running turn completion
- Auto-detection -- detects iTerm2, Ghostty, WezTerm, Kitty, and falls back to BEL
- Configurable threshold -- only fires when turn exceeds N seconds (default: 30s)
Workspace Boundary & Trust Mode (TUI-8)
- Three sandbox modes --
read-only,workspace-write(default),danger-full-access - Trust mode -- bypass approval for non-destructive reads outside workspace
- Explicit allow/deny lists -- fine-grained path-level control
- Violation tracking -- all policy violations are logged
Draft Stash System (TUI-9)
- Multi-entry stash --
Ctrl+Sto stash,/stash listand/stash popto manage - Buffer management --
Ctrl+Uclear +Ctrl+Yrestore for single buffer
Enhanced Cost Tracking (TUI-10)
- Per-turn breakdown -- input/output/cached/reasoning token counts with cost
- Cache hit rate -- per-turn and session-level cache utilization metrics
- Pricing registry -- configurable per-model pricing (built-in for GPT-4o, Claude, DeepSeek)
- Session aggregation -- total cost, tokens, and by-model grouping
- Status line display -- compact token/cost indicator
Approval Policy Engine (TUI-11)
- Three policies --
on-request(ask per command),auto(YOLO),never(block all) - Auto-allow prefixes -- commands matching configured prefixes bypass approval
- Mode-aware strictness -- plan mode requires approval for unknown commands
- Integration -- extends existing
danger.py4-level classification
Job Center (TUI-12)
- Shell job registry -- tracks all shell commands with status, output, and timing
- Output tailing -- last 50 lines of output per job
- Linked tasks -- jobs can reference durable task IDs
- Job lifecycle -- running -> completed/failed/cancelled with cleanup
Agent View - Multi-Session Dashboard (TUI-20)
- Session dashboard -- at-a-glance view of all concurrent agent sessions with status indicators
- Peek panel -- preview the last response of any session without switching context
- Inline reply -- respond to waiting sessions directly from the dashboard
- Background sessions -- send any session to the background with
/bg - Session types -- distinguishes Chat and Goal sessions with visual indicators
- Auto-refresh -- session statuses update every 2 seconds
Background Agent Runner (TUI-21)
- Async workers -- up to 10 concurrent background agent sessions
- State persistence -- session state survives TUI restarts via TaskManager
- Crash recovery -- interrupted sessions are marked as failed on restart
Autonomous Goal Loop (AU-ORCH.session.durable-session-autonomous-goal)
/goalcommand -- define an objective and let the agent work autonomously- Natural language parsing -- supports
until <end_state>andwithout <constraints>patterns - KG-native goals -- goals are persisted as GoalNode entities in the Knowledge Graph
- Context enrichment -- goals are auto-enriched with codebase context from the KG
- Rule validation -- goals are checked against the project constitution before execution
- Historical leverage -- prior goal outcomes inform new goal planning
- Durable checkpoints -- goal state is checkpointed for crash recovery
- Validation commands -- auto-extracts shell commands from end-state criteria
User Experience
- Message queuing -- queue messages while agent is processing; related queries are intelligently combined using regex patterns for conjunctions, sequential actions, and similar structure
- Exit confirmation -- modal dialog prevents accidental termination via Ctrl+C or
/exit - Terminal transparency -- UI respects your terminal's transparency settings for seamless integration
- Theme system -- Textual's built-in themes (default tokyo-night; nord, gruvbox, dracula, and more) switchable with
/theme
Commands
- Slash commands -- comprehensive command set for common operations:
/help-- show available commands/clear-- clear the current event log/mcp-- browse connected MCP servers and their tools/history-- browse and select from historical chat sessions/image-- attach images to messages/init-- initialize a new project or workspace/review-- review code and suggest improvements/test-- run tests on the current codebase/search-- search through code and documentation/ask <question>-- answer a data question in plain English (multi-step analyst)/nl <question>-- translate a question into a graph query and run it (/nl preview ...to dry-run)/obs <promql>-- query observability metrics;/obs range <promql>(sparkline),/obs traces [service]/broker-- engine message-broker status (stats/queues/exchanges)/kvcache-- shared KV-cache occupancy and dedup stats/capabilities [query]-- search the live catalog and generate an action form/capability <id>-- inspect one live capability descriptor/run [run_id]-- follow a run in Mission Control, or browse recent runs when no ID is known/stats-- show statistics about the current session/fleet-- show fleet topology and pending approvals;/fleet grant <id>to approve/cost-- show token and cost tracking information/queue-- show current message queue status/queue:clear-- clear all queued messages/queue:toggle-- enable/disable message queuing/model-- switch between available models used by SI agents/theme-- switch between available themes/compact-- compact conversation context to save tokens/diff-- show interactive diff viewer for recent changes/recap-- summarize the session context/fast-- toggle fast mode (Haiku/Flash models)/memory-- manage project memory (AGENTS.md)/agents-- list available specialized agents/add-dir-- add a directory to the agent's working context/restore N-- restore workspace to snapshot at turn N/sessions-- list and manage durable sessions/trust-- toggle trust mode/sandbox-- set sandbox mode (read-only / workspace-write / danger-full-access)/approve-- set approval policy (on-request / auto / never)/jobs-- list and manage shell jobs/tasks-- list and manage background tasks/stash-- manage input draft stash/hooks-- show lifecycle hook status/exit,/quit-- exit the application with confirmation/goal <text>-- start an autonomous goal loop/goal:status-- show current goal progress/goal:cancel-- cancel the active goal/goal:history-- browse past goals from the Knowledge Graph/agents-- open the Agent View multi-session dashboard/bg-- background the current session/attach <id>-- attach to a specific session
Input Prefixes
!-- Direct Bash execution (e.g.,!ls -la)@-- Fuzzy file mention autocomplete (e.g.,@app.py)
Backend Integration
- Unified specialist visibility -- MCP agents and A2A peers appear identically in the workflow sidebar; both emit the same sideband events via the backend's
discover_all_specialists()unified roster - Tool-count telemetry --
tools-boundsideband events includetoolset_count,dev_tools, andmcp_toolsbreakdowns for per-specialist visibility - Real-time token and cost tracking -- integrated in the status line for session monitoring
- Memory Auto-loading -- backend automatically includes
AGENTS.mdandMEMORY.mdin the system prompt for project-aware reasoning.
Usage
Start the Arbora-hosted agent-utilities backend server, then launch the TUI:
agent-terminal-ui
Or run with uv if installed locally:
uv run agent-terminal-ui
Headless mode
Run a single prompt without the TUI, streaming the response to stdout. No Textual widget tree is loaded, so a headless instance is lightweight (~30MB) -- suited to running many concurrent, non-interactive sessions against one shared backend.
agent-terminal-ui --headless --prompt "summarize the open PRs"
agent-terminal-ui --headless --prompt "run the tests" --model claude-opus-4-8
Docker
A slim, runtime-only image (Dockerfile, python:3.13-slim) ships the frontend
without test/shell extras or the agent_utilities backend. Point it at a shared
backend with AGENT_URL:
docker build -t agent-terminal-ui .
docker run --rm -e AGENT_URL=http://agent-utilities:8000 \
agent-terminal-ui --headless --prompt "status report"
Because the backend is the heavy component, run one backend service and many lightweight frontends against it.
Keyboard Shortcuts
- Ctrl+C -- Interrupt generation or cancel current operation
- Ctrl+D -- Exit session (with confirmation)
- Ctrl+L -- Clear the event log
- Ctrl+O -- Toggle workflow sidebar
- Ctrl+S -- Stash current input draft
- Ctrl+T -- Toggle task list view
- Ctrl+U -- Clear input buffer
- Ctrl+Y -- Restore cleared input buffer
- Alt+P -- Switch the model used by the SI agent
- Alt+T -- Toggle Extended Thinking (for reasoning models)
- Alt+O -- Toggle Fast Mode
- Shift+Tab -- Cycle reasoning effort (OFF → HIGH → MAX)
- Ctrl+R -- Reverse history search
- Ctrl+H -- Show help overlay
- Tab -- Navigate between focusable elements
- Esc Esc -- Rewind/Undo (experimental)
- Left Arrow -- Switch to Agent View dashboard
- Right Arrow / Enter -- Attach to selected session (from Agent View)
Message Queuing
When the agent is processing, your input is automatically queued. The system intelligently combines related queries using patterns like:
- Conjunctions: "and", "also", "plus", "then", "after that"
- Sequential actions: semicolon-separated commands
- Similar structure: same action verbs (fix, add, remove, update, create, delete, implement, refactor)
Example: If you type "fix the bug in app.py" followed by "and add a test for it", these will be combined into a single query.
Environment Variables
| Variable | Default | Purpose |
|---|---|---|
AGENT_URL |
http://localhost:8000 |
Arbora base URL for A2A chat and REST operations |
AGENT_BEARER_TOKEN |
unset | Caller credential for Arbora; required for remote endpoints |
AGENT_THEME |
tokyo-night |
Startup theme (any Textual built-in theme name) |
The /op command requires Python 3.12 or newer and an installed Arbora
distribution containing its generated client. The package, including basic chat,
supports Python 3.12 or newer. CI and release validation use Python 3.14. Without the generated client, /op refuses with CLIENT_UNAVAILABLE.
Themes
The TUI uses Textual's built-in themes. The default is tokyo-night; others include nord, gruvbox, dracula, monokai, textual-dark, and textual-light.
Switch themes live with the /theme <name> command, or set the startup theme via
the AGENT_THEME environment variable.
Development
Prerequisites
Setup
Create uv virtual environment and install dependencies:
uv sync --frozen --all-groups
To update dependencies (updates the lock file):
uv sync --all-groups
Run formatting, linting, and type checking:
uv run ruff format && uv run ruff check --fix && uv run ty check
Documentation
Start at the Agent Terminal UI documentation. It includes Architecture, Features, and Configuration references.
Contributing
See AGENTS.md for contribution and validation guidance.
License
Agent Terminal UI is released under the MIT License.
Metadata
Release files for agent-terminal-ui 2.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agent_terminal_ui-2.3.0.tar.gz | 287.6 kB | Without provenance | Details for agent_terminal_ui-2.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agent_terminal_ui-2.3.0-py3-none-any.whl | Python 3 | none | any | Details for agent_terminal_ui-2.3.0-py3-none-any.whl |
Total release size: 499.8 kB
Release files / agent_terminal_ui-2.3.0.tar.gz
| Download URL | agent_terminal_ui-2.3.0.tar.gz |
|---|---|
| Size | 287.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
dc64d617ce8543225865484ced2de954d71c89b19080aa0972cd4d43551f8a63
|
|
BLAKE2b-256 checksum How to use checksums |
78d2fc0ebfbf3fd4f5cc55975a4c6c93302394feb08680b26d3b67a921a3476f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.4
|
Release files / agent_terminal_ui-2.3.0-py3-none-any.whl
| Download URL | agent_terminal_ui-2.3.0-py3-none-any.whl |
|---|---|
| Size | 212.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5705c526251a594594a2141728b9dbe1009bf4b525a8f02a45601726dc2ee638
|
|
BLAKE2b-256 checksum How to use checksums |
cfcb43c2d8c7ac8dfe6ca84231d82ff82f5928643d17443404c33925ec682708
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.4
|
Security for agent-terminal-ui 2.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.