TUI Control MCP Server

Prerequisites: the GAIA TUI binary, started with the control API on: gaia tui --control.

Overview

The GAIA TUI can expose a loopback control API, and this MCP server wraps it as tools. An assistant then navigates the hub, types into chat, and launches agents in the session you are looking at — same process, same terminal, frames updating live. It is not a headless replica and not a replay. That makes two things possible that were not before:

Testing the TUI without a human at the keyboard. Send keys, wait for a condition, read the rendered screen, assert.
Watching an assistant work. You keep your terminal open; navigation, filtering, and agent launches happen in front of you.

┌──────────────┐    stdio/HTTP    ┌───────────────────┐
│ Claude Code  │ ◄──────────────► │ TUI Control MCP   │
│ / MCP client │     MCP tools    │ server (Python)   │
└──────────────┘                  └─────────┬─────────┘
                                            │ loopback HTTP + bearer token
                                            │ (discovered via ~/.gaia/tui/control.json)
                                            ▼
                                  ┌───────────────────┐
                                  │ gaia tui --control│  ← the terminal you are watching
                                  │ (Go / Bubble Tea) │
                                  └───────────────────┘

Keys are injected into the running tea.Program with Send; the screen served back is the exact frame the renderer just drew.

Available Tools

Tool	Description
`tui_status`	Is a TUI running, and what is on screen conceptually: view, active agent, streaming, hub tab, selection, terminal size
`tui_screen`	The rendered screen as plain text (ANSI stripped). The workhorse — read it after every action
`tui_send_keys`	Inject named keys: `enter`, `esc`, `tab`, `shift+tab`, arrows, `pgup`/`pgdown`, `backspace`, `ctrl+c`, `?`, `/` …
`tui_send_text`	Type a string as runes (what a human typing produces)
`tui_wait_for`	Block until text appears (or disappears), with a timeout. Use this instead of polling
`tui_launch_agent`	High level: find the agent by id across hub tabs, move the selection, launch it
	(refuses in a standalone `gaia chat` session, where esc quits instead of returning to a hub)
`tui_install_agent` / `tui_uninstall_agent`	High level: navigate to an agent and trigger the hub’s install/uninstall binding
`tui_resize`	Re-lay-out at a given size, e.g. 80x24 versus 200x50

tui_install_agent needs an install keybinding on the hub screen, and the hub does not have one yet — the tool reads the bindings off the footer rather than guessing a key, so today it returns “not yet available” and lists what the hub does offer. It starts working the moment the binding lands, with no change here. Neither tool takes “the key was pressed” as success: tui_uninstall_agent requires the agent to be gone from the hub’s list, and tui_install_agent requires the screen to have changed at all (an install promotes the row to a different tab, so it may legitimately leave the current one). A refusal quotes the hub’s own status line.

tui_wait_for is the one that makes automation reliable. Without it, every caller busy-polls tui_screen and races the render. On timeout it reports what the screen actually contained, so a failure is debuggable.

tui_send_keys, tui_send_text, and tui_resize return only once the input has been consumed and redrawn, so reading tui_screen immediately after is race-free. They report settled: false if the model was still busy — the input is queued, so re-read the screen rather than assume it was dropped. That is not the same as “the consequences finished”. Pressing enter to launch an agent is consumed at once, while the view switch it starts arrives a moment later — so wait on the outcome (tui_wait_for) rather than reading the screen once and concluding nothing happened. If the user has quit the TUI (or it is still starting), these tools fail with “the TUI is not accepting input” instead of reporting a success. Bubble Tea discards messages sent outside its event loop, so a success there would be a lie. tui_status and tui_screen keep working, and tui_status reports running: false.

Setup with Claude Code

Start the TUI with the control API

gaia tui --control

The TUI prints the port it bound and writes ~/.gaia/tui/control.json (mode 0600) holding the pid, port, and bearer token. The token is never printed. Add --debug to log every injected key, state transition, and wait resolution to stderr.For a fixed port: gaia tui --control-port 8770.

Add the MCP server to Claude Code

# Project-scoped (recommended)
claude mcp add gaia-tui -s project -- uv run python -m gaia.mcp.servers.tui_mcp --stdio

# Or user-scoped
claude mcp add gaia-tui -s user -- uv run python -m gaia.mcp.servers.tui_mcp --stdio

Start a new Claude Code conversation

MCP tools are loaded at conversation start, so open a new one. Ask for tui_status first — it confirms the assistant can see your session.

The server can also run over Streamable HTTP, the same as the Agent UI MCP server:

gaia mcp tui                 # HTTP on :8767  → http://localhost:8767/mcp
gaia mcp tui --stdio         # stdio, for Claude Code
gaia mcp tui --port 9100     # custom port

# Equivalent module invocations
uv run python -m gaia.mcp.servers.tui_mcp --stdio
uv run python -m gaia.mcp.servers.tui_mcp --port 9100

Usage Examples

Navigate the hub

"Show me what's on the TUI right now, then switch to the Available tab
 and tell me which agents are listed."

The assistant calls tui_status, tui_send_keys(["tab"]), tui_wait_for, and tui_screen. You watch the tab change in your terminal.

Launch an agent and ask it something

"Launch the email agent in the TUI and ask it to triage my inbox."

tui_launch_agent("email") walks the hub tabs until the agent is visible, moves the selection onto it, presses Enter, and waits for the chat view to open. Then tui_send_text + tui_send_keys(["enter"]) sends the query.

Check the layout at a small terminal

"Resize the TUI to 80x24 and check nothing overflows."

tui_resize(80, 24) followed by tui_screen.

Discovery and Trust

The MCP server finds the TUI by reading ~/.gaia/tui/control.json — there is no fixed port. Before trusting it, it checks both:

the recorded pid is alive, and
GET /control/v1/status answers with our service id and a matching pid.

Either check failing means the file is stale: after a crash it can point at a port some unrelated process now owns. The tool then says so and names the remedy rather than talking to a stranger’s socket. Every error is structured and actionable — no tracebacks, no leaked URLs, and never the token. With no TUI running, every tool answers with exactly that, plus the command to start one.

Anything that can read ~/.gaia/tui/control.json can drive your TUI. Start the TUI without --control (the default) when you do not want that.

Configuration

Flag	Default	Description
`--stdio`	off	Use stdio transport (for Claude Code)
`--port`	`8767`	HTTP MCP server port
`--host`	`localhost`	HTTP MCP server host

Environment:

Variable	Description
`GAIA_TUI_HOME`	Directory holding `control.json` (default `~/.gaia/tui`). Both halves read it, so tests can isolate a run from your real session.

Troubleshooting

'No GAIA TUI is running'

The control file does not exist. Start the TUI with gaia tui --control (plain gaia tui does not expose the API).

'stale control file' / pid is not running

A previous TUI crashed without cleaning up. Start a fresh one with gaia tui --control — it overwrites the registration.

Keys seem to do nothing

Check tui_status first: a help overlay or confirmation dialog swallows keys until it is dismissed (esc). If the hub still shows Loading..., it has not received a terminal size — call tui_resize.

tui_wait_for keeps timing out

The timeout reports the screen it actually saw. Compare it with what you were matching on — styling is stripped in plain mode, so match on the text, not on box-drawing characters. gaia tui --control --debug logs every injected key and every wait resolution to stderr.

TUI control API reference

The HTTP endpoints, flags, and discovery file this server wraps.

Agent UI MCP Server

The same idea for the browser-based Agent UI.

Getting Started

C++ Framework

Python Framework

TUI Control MCP Server

Overview

Available Tools

Setup with Claude Code

Usage Examples

Navigate the hub

Launch an agent and ask it something

Check the layout at a small terminal

Discovery and Trust

Configuration

Troubleshooting

TUI control API reference

Agent UI MCP Server

​Overview

​Available Tools

​Setup with Claude Code

​Usage Examples

​Navigate the hub

​Launch an agent and ask it something

​Check the layout at a small terminal

​Discovery and Trust

​Configuration

​Troubleshooting

​Related

TUI control API reference

Agent UI MCP Server

Overview

Available Tools

Setup with Claude Code

Usage Examples

Navigate the hub

Launch an agent and ask it something

Check the layout at a small terminal

Discovery and Trust

Configuration

Troubleshooting

Related