The Terminal Hub and the Agent UI are two front ends over the
same agents and the same background service. Use the hub when you live in a
terminal or are on a headless box; use the Agent UI when you want file drops,
rendered cards, and a browser.
gaia tui is the Go terminal binary. Building from source it is tui/bin/gaia
(cd tui && make build) — it accepts a leading tui word and drops it, so
./tui/bin/gaia and ./tui/bin/gaia tui open the same screen. See the
CLI reference for its non-interactive
subcommands.The hub screen
The hub opens on the agent list, grouped into three categories:- Installed — on this machine, ready to run.
- Available — published on the Agent Hub, not installed yet. On a fresh machine Email Triage starts here.
- Coming Soon — announced but not published. These can’t be installed; you can vote for them.
Backspace is deliberately unbound. Everyone presses it meaning “go back”, and on
this screen that would be one keystroke away from a destructive action.Installing an agent
Select it and pressi. That is the whole flow — there is no shell command you need
to remember. (For scripts and CI there are non-interactive equivalents; see the
CLI reference.)
An agent outside the verified security tier runs third-party code on your machine,
so GAIA asks first rather than installing quietly. The prompt names what you’re
agreeing to — the agent id, version, publisher, security tier, download size, and
the access it declares — plus the background service’s own reason for refusing the
install until you say yes.
Cancel is focused by default. y trusts and installs, n or Esc cancels,
←/→ moves between the buttons, Enter picks the focused one.
If an install fails, the result box stays up with the reason. i or r retries it;
Esc, q, n, or Enter dismisses. Dismissing never cancels an install that is
still running — the background service owns that work, and a half-removed install
directory is worse than waiting.
The readiness check
PressEnter on an installed agent and GAIA checks its preconditions before starting
it. This runs on every launch, not just the first, because any of these can break
between sessions.
checked once "X" is fixed means exactly that: the check did not run, so the screen never shows you a
verdict it couldn’t have reached. A [ ] row is not a pass and not a failure.
Where a fix can be automated, it’s one key. The failing row offers f and the
footer repeats it. f on the row above starts the agent; the count went 1 of 5 →
2 of 5 and the check moved on to the next row on its own.
Markers
The marker and the words carry the state on their own, so the screen reads the same
on a monochrome terminal or piped to a file.
Keys
Enter is not offered while a row is failing. Press it anyway and the screen names
the blocker rather than starting something that would fail on its first action. It
is offered when a row is merely unverified ([?]) — nothing there says anything is
broken.
When the fix can’t be automated
Some fixes can’t be done from a terminal UI. GAIA does not open a browser behind your back or half-implement a flow that already works elsewhere. It hands you the command and waits:r. The re-check is the
loop: fix something, r, read the new count. Esc goes back to the checks without
re-running them.
Other rows behave the same way when they can’t self-heal — the Local AI row, for
instance, offers no f (the model server keeps the terminal it starts in), so the
footer drops to r re-check · d details · esc back and the row prints the command
to run.
Filing a bug about a check
Pressd on the failing row. That shows the raw answer the probe got — the HTTP
status, the body, the timing — which is what a maintainer needs and what prose
summaries lose.
The chat screen
Once the checks clear, GAIA starts the agent and drops you into the conversation. The chrome is the same for every agent — the agent’s name appears in the title bar, theConnected to: line, and the status line:
Next steps
- Email Triage — the first agent on the hub, end to end.
- CLI reference — the non-interactive
subcommands (
list,status,run --query) and their exit codes. - Driving the TUI programmatically — the control API, for tests and assistants. Not needed for normal use.