The TUI and its keys

Bare orrery at a terminal opens the TUI: a banner, the thread, a dock for questions, the input, and a footer with the permission mode, key hints, tokens, cost and model.

The footer's context percentage is the last prompt against the model's own window: [windows."<model>"] in config, else the window the provider runs it at, else what the provider's model list reports, else the window its extension declares. A /model switch switches the window with it (see config keys).

The default client is drawn with ratatui. It is an extension like any other client; --ui <id> picks another (see Clients).

#While it starts

The TUI opens before your extensions are up. Until they are, the line under the input says starting extensions…. You can type already: what you send waits (… · 1 waiting) and goes the moment they are up. Esc takes it back, and ^D quits at once.

This wait is usually a fraction of a second. It is longer the first time after an install or update, when each extension starts once to say what it offers and an antivirus scans the new executables. If Orrery cannot start at all, the input says orrery could not start with the reason under it; ^D quits and prints the reason again.

#Commands

Type / to list them. Tab completes.

Extensions add their own. For example, the agents extension adds /agents, and the theme extension adds /theme and /theme toggle.

Whatever a command asks, a list, a question or a form, is drawn in the dock, directly above the input, under a rule with its title. Esc cancels it; nothing is saved until its last step.

#Keys

#What you see while it works

Under the newest line, the agent's state: thinking · 3s, running shell · 5s, needs approval, needs your answer. Every tool call is one folded line with its state, name and main argument, for example ● bash git diff --stat. Its output stays folded until you open it.

Reasoning is streamed and folded by default.

#Placed surfaces

Something shown with a placement (by an extension, by the agent, or by your config) is drawn where it was placed: a column beside the thread (pane.left, pane.right), rows above the input (band), or the status line (footer). Each one is labelled with its owner. See Show things: placements.

• A pane is a quarter of the width. It folds into one band row when that would be under 18 columns, or when the thread would be under 40.
• The band shows at most 3 rows. The rest are counted in +N more.
• F6 moves the keys into the placed surfaces, one at a time; F6 past the last gives them back to the input without closing anything.
• Esc closes the focused one for this session and gives the keys back. x (or Delete in the Rust TUI) is its ✕: it closes it and moves to the next.
• /ui lists what is placed and moves, hides or saves it (CLI reference).

Limits

• Dismissing is this client's own. Another client attached to the same session still draws the surface, and it comes back in a new session.
• The Ink client focuses a whole pane, not one surface: closing it closes every surface stacked in that pane. It has no Delete key and F6 does not reach the band.
• A pane takes its width from the thread, so the fold rule above decides how many screens get a pane at all.
• A surface that stopped (its extension crashed) is drawn dimmed, labelled stopped, with the fix the screen names: /ext restart <id> (CLI reference).
• A terminal with no graphics protocol shows an image as its text alternative.

#Look

• /theme previews graphite, paper, ansi-16 and mono when the theme extension is enabled.
• ORRERY_THEME=<name> starts in a palette.
• NO_COLOR (or TERM=dumb) draws in mono.
• ORRERY_GRAPHICS=kitty|iterm2|sixel|none overrides how the animated mark is drawn.

#Down a pipe

When stdin or stdout is not a terminal, orrery reads one line of stdin at a time and writes events as JSON lines. See One-shot runs.