TUI Mode

The TUI (Terminal User Interface) is UGENT's primary interactive mode. It provides a rich terminal experience with streaming, code highlighting, sub-agent monitoring, and debug panels.

Starting the TUI

ugent

Or from a specific workspace:

cd /path/to/project && ugent

Layout

The TUI has several panels:

• Chat area — streaming assistant responses with syntax highlighting
• Input box — multi-line input with text selection, word wrap, and auto-complete
• Sub-agent panel — live worker status (role, task, state, iteration count)
• Debug panel — logs, warnings, plugin status, context metrics
• Status bar — model name, token usage, cache hit rate, cron status
• Smart mascot — animated status indicator (working, thinking, idle, sleeping)

Key Bindings

Input

Key	Action
Enter	Send message
Shift+Enter	New line
Ctrl+A	Move cursor to start of line
Ctrl+Shift+A	Select all + copy
Ctrl+Shift+W	Select word at cursor
Alt+Shift+Left/Right	Extend word selection

Navigation

Key	Action
Esc	Stop current turn (like Ctrl+C for the agent)
Ctrl+C (empty input)	Exit UGENT
Ctrl+C (with text)	Clear input

Panels

Key	Action
Click debug card + c	Copy activity ring buffer
Click sub-agent row + Enter	Open worker detail
Shift+Enter (sub-agent panel)	Expand all worker details
q	Close detail view

Slash Commands

/setup              Configuration wizard
/model              Switch LLM model
/providers          Manage provider instances
/context enable     Enable context engine
/context status     Check sync status
/context force-sync Force re-index workspace
/cron               Manage scheduled jobs
/cron review        View recent cron run history
/swarm status       Show P2P swarm status
/swarm peers        List connected peers
/firewall status    Injection firewall metrics
/firewall pins      List MCP tool pin status
/tasks              Manage task lists
/status-bar         Toggle mascot / pixel animation
/reload             Reload configuration

Streaming

Assistant responses stream token-by-token. Reasoning steps (thinking blocks) are shown in a collapsible widget. When the agent calls a tool, a live status row appears showing the tool name and elapsed time.

Sub-Agent Panel

When the orchestrator delegates tasks, the sub-agent panel shows:

• Worker role (Coder, Researcher, Tester, etc.)
• Task name and state (Running, Waiting, Completed, Failed)
• Iteration count
• Active tool or latest activity
• Terminal summary for completed workers

Cron Indicator

The status bar shows a cron indicator when scheduled jobs are running. Completed and failed jobs update the cron status area. Use /cron review to inspect run logs.

Context Compaction

When the context window approaches the limit, UGENT automatically compresses older messages. The status bar shows context compacting... N% during compression, then context compacted 100% briefly after completion.

Terminal Compatibility

UGENT runs on:

• SSH sessions (OSC 52 clipboard support)
• tmux and zellij (with Zellij-conservative input defaults)
• Herdr terminal multiplexer (pane state reporting + toast notifications)
• Ghostty, Warp, Alacritty, iTerm2, WezTerm, Windows Terminal + WSL

Input feature policy is environment-overridable:

UGENT_TUI_MOUSE_CAPTURE=auto
UGENT_TUI_BRACKETED_PASTE=auto
UGENT_TUI_KEYBOARD_ENHANCEMENT=auto