gaia-tui is GAIA’s terminal-native front door. It opens directly on the flagship
gaia agent — conversation, documents, data, web research, memory, skills — behind a
readiness gate that runs on every launch and checks the few things that would
otherwise make the agent fail. Where it can fix a problem itself, one key does it.
Where it can’t, it says so and gives you the exact command.
Download the installer for your platform from amd-gaia.ai,
run it, then open a new terminal:
The Terminal UI and the Agent UI are two front ends over the same
agents. Use the terminal when you live in one or are on a headless box; use the Agent
UI when you want rendered cards and a browser. Both take a dropped file or a pasted
screenshot.
gaia-tui is the Go terminal binary — never gaia, which is the Python CLI’s
name and has entirely different subcommands. It accepts a leading tui word and
drops it, so gaia-tui and gaia-tui tui open the same session. See the
CLI reference for its non-interactive
subcommands.Installing
Every release publishes a native installer per platform, at amd-gaia.ai (the page picks your platform) and on the GitHub release. Each puts two binaries on disk and on your PATH —gaia-tui (this hub) and gaia-agent (the flagship agent
the hub runs) — so there is nothing to unzip and nothing to chmod.
The Windows setup is per-user: it needs no administrator rights and shows no UAC
prompt. It also bundles Lemonade Server, so the install itself needs no network
(Lemonade downloads its own runtime the first time you run a model). Start Menu
and desktop shortcuts are created; open a new terminal afterwards, because an
already-open one keeps the PATH it started with. Quit GAIA before upgrading —
Windows cannot replace a running program, and the setup will tell you so rather
than install over it half-way.
There is no installer for Windows on Arm or Linux on Arm. The flagship agent
publishes no build for either, so an installer there would set up the hub with no
agent behind it. The raw
gaia-tui binary is still published for all six targets
if you want to run the hub against an agent you build yourself.~/.gaia — your chats, documents and memory — in place unless
you say otherwise. On Windows, Add/Remove Programs offers to delete it; on Linux,
apt remove and rpm -e keep it. Lemonade Server is never removed with GAIA,
because other things may be using it — see gaia uninstall --purge-lemonade.
A macOS .pkg ships no uninstaller — that is the platform convention, not an
omission — so remove the files and then forget the receipt:
pkgutil --forget drops only the installation receipt
and deletes nothing, which is why the rm comes first. ~/.gaia is untouched either way.
macOS packages are unsigned unless the release was built with Apple credentials
configured. Unsigned, Gatekeeper warns that the package comes from an
unidentified developer. Right-click → Open no longer bypasses that as of macOS 15:
dismiss the warning, then go to System Settings → Privacy & Security and click
Open Anyway next to the blocked package.
Building from source
Contributors who want the binary from a checkout, rather than the installer:gaia-tui only. gaia-agent still has to come from an installer or a
hub download — the readiness gate below says so on the first screen if it is
missing.
The boot sequence
Every launch —gaia-tui with no arguments, or gaia-tui run email — goes
through the same three screens: a splash, a readiness gate, then chat.
1. Splash
The first frame is GAIA’s mascot over the wordmark and tagline, while the readiness gate spins up behind it — the launch never opens on a blank terminal:2. The readiness gate
For the flagship, three things are checked, in order, each depending on the one before it: isgaia-agent on this machine, is the local model server (Lemonade)
reachable, are the models downloaded. The gate stops at the first failure — a
missing model server makes “are the models downloaded” meaningless.
An all-green machine flashes through this screen and lands in chat without a
keypress. A failure holds it open:
f runs gaia init right there and streams its progress into the
screen; esc cancels it. The command is shown only as the copy-paste
alternative — nothing on this screen requires leaving the TUI.
If gaia-agent itself is missing, the gate stops on the first row and sends you
to the installer — there is no in-TUI download for the agent binary:
f: the TUI cannot install its own agent binary, so it names
the installer instead of offering a key that would not work.
email (and any other daemon-supervised agent) goes through the same three
screens, but its gate has five rows instead of three: background service,
sidecar, Lemonade, model, and mailbox. See Email Triage for
that gate end to end.
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 outright. Press it anyway and the
screen names the blocker rather than starting a chat that cannot talk. It is
offered when a row is merely unverified ([?]) — nothing there says anything is
broken.
3. Chat
Once the gate clears, GAIA starts the agent and drops you into the conversation:
By default GAIA owns the mouse, so the wheel scrolls the conversation — a
full-screen terminal app has no scrollback of its own behind it — and a printed
link is clickable. Hold
Shift (Option in iTerm2) to drag-select without
leaving that mode, or press Ctrl+T to hand the mouse back to your terminal
outright.
Typing
/ as the first character of an empty composer opens a palette listing every
command above with a one-line description, so there’s no need to already know them or
open /help first:
/mo above narrows to /model), ↑/↓ to move the
selection, Enter to run it, Esc to close the palette without touching the composer
or cancelling a running turn. A / typed mid-sentence is just a slash — the palette
only opens on an otherwise-empty line.
The mouse works the same list: hovering a row moves the selection there, and
clicking the row that is already selected runs it — the common case, since hovering
already selects before you click. Clicking outside the box closes the palette, same
as Esc. None of this needs a mouse: every path above is reachable from the keyboard
alone.
When an agent asks a follow-up question mid-turn — “Gmail or Outlook?”, say — its
options are the same: ↑/↓ (or Tab) to move between them, a number key to pick
one directly, Enter to answer, and the mouse works identically to the palette above.
Esc cancels the turn rather than the question, since abandoning it is the only way
out once it is up.
A session launched with --use-claude skips first-boot setup entirely and does not
start the local server — that flag exists to avoid the local backend, so running an
installer that launches it would defeat it, and would hold the first answer behind a
multi-minute install. The transcript says the server was not started and names what
still needs it: RAG, memory and the code index embed through Lemonade, which has no
Claude equivalent. Run gaia init --skip-chat-model, or /setup in
the composer, when you want those.
Running another agent
The flagship is the default, butgaia-tui can also drive email by id — it keeps
its own five-row readiness gate:
Colours (light vs dark terminals)
Colours adapt to your terminal automatically. Some terminals never answer that query (SSH, tmux, a CI log) — if the screen comes out hard to read, force a mode:Next steps
- Email Triage — the id-addressed agent, end to end.
- CLI reference — the non-interactive
subcommands (
run,chat,status) and their exit codes. - Driving the TUI programmatically — the control API, for tests and assistants. Not needed for normal use.