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:

• Header — the LLM instance and model in use
• 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 — context use, cache hit rate, session tokens and estimated cost; context-engine sync state (Ctx off, syncing, Ctx err); and LSP, memory, MCP, skill and plugin status
• Smart mascot — animated status indicator (working, thinking, idle, sleeping)

Status Bar

The first segment reads like Ctx 12.3% (24.6K/200.0K) ... Σ 1.2M ~$0.050: how full the context window is for the next request, the cache hit rate of the last call where the provider reports one, the session's total tokens (Σ), and what they cost.

Costs are estimates, marked with a tilde here, in the token panel and in the monitoring cards. They come from the public list prices in UGENT's model catalog, not from your provider's invoice. The TUI reads the same catalog as the agent (UGENT_MODELS_FILE, else the copy built into UGENT), never one in the folder you start it in, so limits and prices are the same wherever you launch it. (The agent's token budgets read [tokens] models_file first when it is set; the TUI does not.)

Key Bindings

Input

Key	Action
Enter	Send message
Shift+Enter	New line
Ctrl+A	Move cursor to start of line
Ctrl+W	Delete the word before the cursor
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 the current turn and the sub-agents it started
Ctrl+C (empty input)	Exit UGENT
Ctrl+C (with text)	Clear input

Panels

Key	Action
Ctrl+D	Toggle the debug panel
Ctrl+I	Toggle the monitoring panel
Ctrl+F	Toggle the sub-agent panel
Click debug or activity panel + c or y	Copy its contents
Click sub-agent row + Enter	Open worker detail
Shift+Enter (sub-agent panel)	Expand all worker details
q	Close detail view
Esc (no turn running)	Clear panel focus and go back to typing; with a task list present, it offers to cancel the tasks

Slash Commands

/setup                      Configuration wizard
/providers                  Manage provider instances
/providers use <instance>   Switch the default instance
/providers model <name>     Switch the default instance's model
/with <instance>[@model] <prompt>
                            Send one message to another instance or model
/live [instance]            Open a realtime voice or text session
/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
/plugin list                Show plugins and their status
/task                       Manage task lists
/status-bar                 Toggle mascot / pixel animation
/reload                     Reload configuration

The full list is in Slash Commands.

Choosing the Model

/providers use <instance> switches the default instance, and /providers model <name> its model. /with <instance>[@<model>] <prompt> sends one message elsewhere without changing either; the next plain message runs on the default again.

A turn that delegates finishes on the model it started on: when its workers are done and the runtime resumes it, the resumption runs on that model, the one /with named included. See Which Model a Turn Runs On.

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.

A model's progress notes (Claude's updates between tool calls, OpenAI's reasoning summaries) show as a one-line Working: ... status, never in the transcript.

Live Sessions

/live [instance] opens a realtime session on an instance whose live model is a realtime one: OpenAI's Realtime API (gpt-realtime-2.1), Azure OpenAI, or Gemini Live.

/live openai-rt         Open a session on the openai-rt instance
/live say hello there   Send a typed turn
/live status            Show whether a session is active
/live stop              End the session

What you say and what the model says both appear in the chat, each line once, and the partial transcript shows in the status line. A provider error is shown and the session carries on; it ends when you stop it or the provider closes it. With the live-audio build, /live captures the microphone and plays replies, stopping playback when you talk over it; without it, sessions run in text mode. Configuration is under OpenAI and Google AI.

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

A cron indicator appears beside the input hint 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 line under the input shows context compacting... N% during compression, then context compacted 100% briefly after completion.

Plugins in a New Folder

A folder with no plugins config of its own falls back to the global ~/.ugent/plugins.toml. A TUI or REPL started there runs only the swarm plugins from that file. Its channel plugins (Slack, Discord and the like) were set up for another folder or for the daemon, and starting them would run a second copy of each beside the one already serving.

The others show as disabled for the session, and /plugin list names them. /plugin enable <id> starts one for this session only, and /plugin setup gives the folder a plugins config of its own. Such a session never writes the global file: an enable or disable lasts for the session, and a full configuration reload starts from the file again. Its run records and plugin logs live in the folder's own instance directory. The daemon is unaffected and starts every enabled plugin.

When the Terminal Goes Away

Closing the terminal or the tmux session sends UGENT a quit signal. If the TUI has not shut down 15 seconds later, the process stops the plugin workers it started, restores the terminal if it can, writes why to ~/.ugent/ugent.log and exits. A second quit signal exits at once. A healthy TUI still shuts down gracefully.

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