agent-terminal-ui

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).

[!NOTE] This library is in early development and subject to change.

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 -- /run discovers 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 with AGENT_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 N to 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+Tab cycling
• 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_env hooks 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+S to stash, /stash list and /stash pop to manage
• Buffer management -- Ctrl+U clear + Ctrl+Y restore 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.py 4-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)

• /goal command -- define an objective and let the agent work autonomously
• Natural language parsing -- supports until <end_state> and without <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-bound sideband events include toolset_count, dev_tools, and mcp_tools breakdowns 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.md and MEMORY.md in 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

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

• uv
• prek

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.