Using gaia ui

You'll learn how to move through the cockpit, read a ticket, create one, and jump straight to the thing you are working on.

gaia ui is a full-screen terminal application. It reads the same control plane your repository is connected to, so start it inside the repository: gaia ui --print-config tells you which connection won if you are not sure.

gaia ui

Three levels, one tab bar each

The cockpit has three levels — root, project, ticket — and every screen shows the tab bar of its own level. Tab and Shift-Tab cycle the tabs; Enter opens the selected row; Esc goes back one level; q quits.

Level	Tabs
Root	Dashboard · Projects · Conductors · Users
Project	Dashboard · Tickets · Ticket-Agents · Runs
Ticket	Overview · Comments · Related · Runs

Opening a project lands on its Dashboard — the same statistics screen, scoped to that project. Its ticket list is one Tab away. Conductors lists the conductors in your workspace, filtered to the ones you own (press m to see every conductor and m again to return to the default), with their liveness; s starts the selected one, x stops it, Enter opens its log. Users lists accounts with their 30-day tickets, runs and closed-per-run.

The Dashboard

Ticket and run activity for the last 24 hours, 7 days and 30 days: how many tickets closed, how many runs happened, and closed per run — a rough measure of how much run effort a finished ticket costs. This is the same screen rendered as text by gaia ui | cat:

GAIA dashboard
TICKETS CLOSED
  Last 24 hours █░░░░░░░░░░░░░░░░░░░ 3
  Last 7 days ██░░░░░░░░░░░░░░░░░░ 9
  Last 30 days ████████████████████ 79
RUNS CREATED
  Last 24 hours █░░░░░░░░░░░░░░░░░░░ 18
  Last 7 days ██░░░░░░░░░░░░░░░░░░ 50
  Last 30 days ████████████████████ 579
CLOSED PER RUN
  Last 24 hours                     0.17
  Last 7 days                       0.18
  Last 30 days                      0.14

Below those, the root Dashboard breaks the figures down per project and per user; a user row opens that person's Overview, Tickets and Runs. Bars scale against the largest value in their group, so a full bar means "the biggest of these", never "100 %".

Tickets

A project's Tickets tab lists its tickets, closed ones hidden by default — the footer says how many that is holding back. ↑↓ select, Enter opens, ←→ page. The filters are single keys:

Key	Filter
/	search — matches are highlighted
s	cycle the state filter
x	cycle closed: hidden → only → all
w	the Who filter — pick an assignee
m	mine — the one-key shortcut onto Who for yourself
p	the parent filter — tickets under one parent
c	clear every filter back to the defaults (closed hidden again)

Reading a ticket

The header box shows the title, the ticket's labels and its state, and stays put on every section. Rendered as text (gaia ui GAIA-427 | cat), a ticket opens like this:

GAIA-427 · User documentation: Storybook-style guide for teams that use GAIA
State
coding
Labels
work:docs
Parent
No parent ticket.
Latest summary
No summary comment.
Latest spec
— spec · pg · 2026-09-07T16:24:09+00:00
Design spec — committed
…

• Overview starts with the latest summary — the newest handoff that says where the work stands — then the latest spec and plan when they exist, then the description. Each is collapsed to a short extract; Enter or Space expands the selected one, ↑↓ moves between them. Above them: the parent ticket and the links (the merge request, once coding opened one).
• Comments lists every comment newest first, rendered as Markdown, each under a marker that names its type, author and time.
• Related shows the parent, the tickets this one is blocked by, and the counts of sub-tickets and referenced tickets.
• Runs lists the ticket's runs, newest first. Enter on a run opens its detail — state, phase, agent, conductor, timing, the footprint (tokens, tool calls, turns), the worktree, and the full log and error log. Esc comes back.

e opens the edit popup: assignee, conductor, estimate and spent time, parent, labels. Ctrl+S saves. Cancel ticket is a second action on tickets that are not yet done — it writes state: cancelled at once, with no confirmation step.

Creating a ticket

Press n on the Dashboard, the Projects list or a Tickets list. The popup asks for a title, a Markdown description, an optional parent, and the assignee, conductor, labels and workflow — your own user and this checkout's conductor are preselected. ↑↓ or Tab move between fields, ←→ change a select, Space toggles a label, Del clears the conductor.

Finish with one of two actions:

• Create directly (Ctrl+D) writes the ticket as typed. It needs a project in scope, so open a project first, and a title.
• Create with agent (Ctrl+S) hands your input to a ticket-create agent that interviews you for whatever is missing, writes the acceptance criteria, creates the ticket and routes it. The agent runs in the project's Ticket-Agents tab, where Enter brings it to the front, z tiles all agents and x closes one.

Esc cancels. Create a ticket compares these with the other creation paths.

Jumping straight to something

The cockpit takes one deep-link target on the command line — at most one:

gaia ui GAIA-221                 # a ticket, by identifier (case does not matter)
gaia ui project:shop             # a project's Dashboard
gaia ui run:<uuid>               # a run's detail, over its ticket's Runs tab
gaia ui --here                   # this branch's ticket, else this repository's project
gaia ui GAIA-221 --view teaser   # a compact block instead of the tabbed detail

--here reads the ticket identifier out of the current branch name (feat/gaia-221-… → GAIA-221) and falls back to the project that claims the repository's git remote. A bare number or a bare uuid is rejected — say ticket:, project: or run:.

A deep link is not a dead end: Esc from a deep-linked ticket opens the Dashboard.

Reload

R reloads the active screen. Anything that can write a file can also trigger it: an interactive cockpit watches .gaia/ui-refresh in the project, and touch .gaia/ui-refresh reloads what R would. Agents and hooks use that to keep your screen current without finding your process.

Without a terminal

Piped or redirected, gaia ui <target> | cat prints the target once — a ticket's sections, a run's detail, the Dashboard's rows (a project: target prints that project's statistics, not its ticket list) — and exits. That is the same rendering the screen uses, so a script or an agent reads exactly what you would see. A ticket list from a script is a gaia dropsh search gaia_ticket --bundle gaia_ticket --filter project_id.id:<uuid> away. --view teaser shrinks a ticket to its identity block:

GAIA-427 · User documentation: Storybook-style guide for teams that use GAIA
state      coding
status     idle
since      —
assignee   —
claim      —

Next

• gaia ui — the full reference: every screen, the deep-link grammar, every key.
• Create a ticket — the popup beside the other creation paths.
• Run a ticket: from claim to done — what the Runs tab is showing you.