Vocabulary is GLOSSARY.md. Session, turn, step, step boundary, action, tool
call, job, delegate, compaction, steering message, client and driver mean what it
says there and nothing else. The events the terminal reads are
docs/events.md; the commands it sends are docs/invocation.md, "Driver
commands".
What the terminal is
The terminal ships in the fiber binary, and the hub serves no UI. It
ships in the binary so that a fresh machine or an SSH box has a door with
nothing installed, not because it has powers another client lacks. A GUI, a
phone app or a web page is a client of the hub with exactly the terminal's
powers (docs/invocation.md, "The hub"). Which of them are first-party is
decided by the application that needs them, not here.
It is a control center over many sessions. It shows every live session
through the hub, from any project, and one of them on screen at a time. It
runs from any directory.
It is written in Rust with ratatui and crossterm, in the fiber binary,
as the tui crate (docs/architecture.md). It prefers existing crates to
writing its own. Their memory is recorded but is not a veto; idle CPU, the
first-frame budget and supply-chain checks stay strict
(docs/dependencies.md, "Measuring memory", and "Performance" below).
It reads the event stream and nothing else. It is its own process and a
client of the hub: a full connection to the session on screen, a
summary connection to each session it has opened, stopped or closed, and
the hub's feed for every other live session (docs/invocation.md,
"Processes"). When a screen
needs data the stream does not carry, the stream changes; the terminal has no
other path to state.
It is full screen only. There is no scrollback mode. The mouse is a
primary input, and every action also has a keyboard or slash-command path
("Keys").
History is paged from the session. The terminal holds a window of
rendered history and asks the session for more with history as the person
scrolls ("History and paging"). It never reads a log from disk, so a local
and a remote terminal page the same way.
An extension may change everything the terminal draws, through the slots in
"Extension seams".
Home
Home is the rail at full width: the same sessions in the same project groups,
with room to say what each one waits on. fiber opens on it. From a session,
← in an empty input box focuses the rail, and a second ← widens it to home
("The rail"); ⌥0, /home, /new and /resume go there too. → or Esc goes
back to the session the person came from. Home has no panel and no rail of
its own. From the top:
the header: the logo at the top left ("The logo"), and beside it two lines
centred on the logo's rows. The first is the version, dim. The second
counts the live sessions across every project by state, each count in its
state's colour ("State glyphs") and joined by a dim " · ", leaving out a
zero count, then the summed spend of the live sessions, dim: "2 waiting on
you · 2 working · 1 retrying · 1 crashed · 2 ready · $5.78 live". With no
live session it reads "no live sessions", dim.
the session list, filling the rows between the header and the input box
("The session list")
the input box, at the bottom where a session's input box sits, so widening
from a session never moves it. Its bottom row carries the workspace chip,
the new worktree switch, the model and thinking chips and "Enter starts a
session".
A key hint sits at the foot: "Enter opens the focused session, or starts one from the box · ↑↓ move · Shift+↑↓ project · Delete stops a live one, deletes an exited one · Backspace archives an exited one · F1 the key map · Ctrl+C twice to quit". Each key shows bold and the rest dim; Enter, Delete, Backspace and Esc name their action's first bound key, leaving an unbound action's part out, while Ctrl+C cannot be rebound so its hint stays fixed. "→ or Esc back to the session" joins it after "↑↓ move", only when home was entered from a session whose row is still live. The key goes back to that session when the box is empty, nothing is open and no notice is up; Esc also goes back with a chip focused, while → then moves between the chips. A session that exited or closed hides the hint and leaves both keys untaken; with the link down or a start in flight the keys are taken as a no-op and the hint stays. Until the first prompt, the input box's
placeholder says "/? for shortcuts". Typing a prompt and pressing Enter asks
the hub to start a session in the chosen workspace, and the screen switches to
it. No session exists before Enter, so opening the terminal, glancing at home
and leaving creates nothing. The first turn waits for any MCP server that
starts with the session (docs/mcp.md, "Starting servers"), and the working
line says so: "Connecting 2 MCP servers…".
On the first interactive run, with no import receipt yet
(docs/configuration.md, "Importing"), home offers a one-time import of
another harness's configuration: Claude Code's or Codex's.
The offer runs the same shared import fiber import runs, and imported
items apply on the next /reload with the reload's usual cache cost
(docs/mcp.md, "Reload"). Accepting the offer opens one import report
overlay ("Look", "Overlays") and adds no notices. A 1 or 2 pressed before the hub connects
still imports once it does, so an early press is never lost. Over a
remote hub connection the receipts are the hub machine's, where that
import runs (docs/configuration.md, "Importing"). The offer fires once: answering it, or running
fiber import first, writes the receipt, and the offer never shows again.
The workspace chip names the workspace in use: the one last picked, else
the directory the terminal was launched in. Clicking it opens the workspace
picker, the same on every client. It is an overlay centred over home, unless
that would cover the input box's top row: then its bottom edge sits on the
row above the box ("Look", "Overlays", "Placement").
It opens browsing, under the title "Workspaces". The first row is the typed
path, "› " in info, the text and the cursor, filled with the chip's
workspace and a trailing /, or ~/ while no workspace is chosen. The
completions sit under it, the focused one on the selection bar, then a
blank row, "── recents ──" dim and the recent rows, dim. With no recent rows
the divider is left out too. The footer is "↑↓ move · Enter open · Esc
closes".
The recent rows are one list: the launch directory, when there is one, then
the recent workspaces from recent.jsonl (docs/state.md), the live
sessions' workspaces then the exited ones', distinct and absolute, ten rows
at most. The list refills as sessions arrive until a key is pressed in the
picker, and again on every row that arrives once Backspace leaves the
recents alone.
The completions are the subdirectories of the directory up to the typed
path's last / whose names start with the text after it: one listing of
that directory, filtered at each keystroke, never a walk of the tree. A
hidden directory is listed only when the typed name starts with .. ~
is the hub's home, and a path that is neither absolute nor starts with ~
has no completions. The listing is the hub's directories command
(docs/invocation.md, "What the hub speaks"), so a remote client's
completions list the hub's machine.
The first completion is focused. ↑ and ↓ move through the completions,
then the recents. Typing edits the path. Tab puts the focused completion
into the path with a trailing / and lists that directory. Enter opens the
focused row as the workspace. With no completion matching, Enter takes the
typed path when it names a directory; otherwise nothing opens and the list
holds one dim row, "no such directory". Backspace past the last character
leaves the recents alone, the first focused.
While no workspace is chosen, the chip reads "no workspace", dim, the
picker's footer is "↑↓ move · Enter open", and Esc does not close it. Enter
on a prompt in that state reopens the picker, sends nothing and keeps the
prompt. A remote client has no launch directory, so its home starts in that
state, with the picker open on ~/.
Until the typed path's directory has answered, the picker shows the typed
row and the recents with no completions, and Enter does nothing. While the
connection is down the "Connection lost" banner shows over home and Enter
stays inert until the connection is back. Enter on ~ alone asks for the
hub's home listing; a later Enter, once it has answered, opens the home
directory. A failed listing shows no completions and no error: the recents
stay, and the directory is not asked again.
The new worktree switch sits beside the workspace chip. When it is on,
the session starts in a new worktree of the workspace, by the same rules a
delegate's worktree follows (docs/invocation.md, "Isolation"). Outside a git
repository the switch is not shown.
The model and thinking chips name the configured model and its thinking level, or the session-only choice while one is pending: then the model chip reads [ⓢ <model>] with only the ⓢ dim, until the session starts or the person picks again. Clicking the model or thinking chip opens the model picker. The thinking chip opens it on the model's thinking levels, with focus starting on the level chips.
The keyboard reaches every part of home. Focus runs top to bottom: the
session list, the entry bar, the chip row. Widening from a session focuses
that session's row; /new, and launching fiber, focus the entry bar;
/resume focuses the first exited row. ↑ and ↓ move through every row, live
and exited, across the project sections. ↓ from the last row focuses the
entry bar, and ↑ from an empty entry bar focuses the last row; on home no
session is on screen, so ↑ there recalls no prompt. ↓ from the entry bar
focuses the chip row, on the chip focused there last, the workspace chip at
first, and ↑ goes back. ← and → move between the chips and stop at the ends. → or Esc goes back to the session home came from when the box is empty and nothing is open; Esc also goes back with a chip focused. Esc is close_or_interrupt's bound key.
Enter on a focused chip does what a click does: the workspace chip opens the
workspace picker, the new worktree switch toggles, the model chip opens the
model picker, and the thinking chip opens it at the model's thinking chips.
The chip stays focused behind the picker. With no session, ↑ on the entry bar
does nothing. Typing while a chip or a row is focused goes to the entry bar,
and so does Backspace on a chip; Backspace on a row acts as "The session
list" says. A focused chip is drawn as a hovered one ("Mouse and hover").
The first frame draws at once. The session list fills in when the hub's feed
arrives (docs/performance.md).
A failed attach says why on home: the session is held, or its status cannot be read ("The session list").
When a session cannot start, as on a fresh install with no key, or after
a person removed the provider they chose, home shows the same lines fiber doctor prints for each blocker, each
with its fix, above the input box (docs/invocation.md, "Commands and flags"). A person
who runs fiber before reading anything is told what to do next.
First run
fiber setup asks the questions a new install needs (docs/invocation.md,
"Commands and flags"). A person who skipped it, or whose install ran without a
terminal, opens the terminal with nothing configured. The terminal then does
the missing steps itself, in this order, each one only if it is not done:
Signing in. No installed provider has a usable credential, counting a
key read from the environment such as OPENCODE_API_KEY. The terminal
opens on home with the /login overlay up ("Logging in"). It opens this
way on every launch until a credential exists, and keeps no record of
having opened. A remote terminal reads the hub's credentials.
The model. No model is configured ("Choosing the model" in
docs/model-routing.md). Once the login's last step saves, the overlay
closes and the model picker opens ("The model picker"), with no row
chosen for the person. Saving writes the config default.
The import offer shows on home as above, once.
A login opened this way closes when its last step saves. A /login the
person typed goes back to the provider list as described in "Logging in".
Esc on the login overlay leaves home with the blocker lines above the input
box ("When a session cannot start", above). Clicking a credential blocker
line opens /login. Enter on home while no provider has a credential keeps
the draft in the box and opens /login. After the login, the draft is still
there to send.
The logo
The logo is ⌇ fiber 0.0.1: the ⌇ in the accent colour, the name in the
accent gradient, the version dim.
On home it is four rows tall and 32 columns wide, at the top left of the
header, in pixel letters drawn with half blocks, with each letter's
counter shaded. The version sits beside it in the header, not after the
name.
Where the terminal speaks an image protocol (kitty, iTerm2 or Sixel), an
image replaces the pixel letters in exactly the same cells: a smooth wave
and the name set in JetBrains Mono ExtraBold, in the gradient. Detection
never delays the first frame. The pixel logo draws first, and the image
replaces it when the terminal's reply arrives. When the terminal reports a cell larger than 64 × 128 pixels, or of zero size, the pixel logo stays.
The image is an alpha mask built from the font with cargo xtask logo-mask and checked in, tinted
with the theme's accents at run time. Fiber bundles no font, and the logo
follows any theme.
Where the screen is too short for four rows, the logo is one row:
⌇ fiber 0.0.1. Fiber cannot tell whether the terminal's font has ⌇, so
tui.logo_glyph switches it to ≈ ("Configuration").
Approving what a repository ships
Extensions, hooks and MCP servers a repository declares are offered by the
session that would load them (docs/extensions.md, "Code a repository
ships"). When the hub starts a session in a workspace whose repository
declares code with no approval for its content, the session raises one offer
before its first model request, so approving costs no prompt-cache rebuild,
and any client can answer it. The terminal shows it in the session's view, as
a swapped view listing every pending item with what an install shows, a diff
for an item whose content changed, and three choices for each: approve, skip
for this session, or never. A package's TUI files are never installed from a
repository, and the offer says so. Each item starts at skip; ↑ ↓ choose an
item, ← → its answer, and Send answers them all at once. Esc puts it aside
behind the approval badge, and ⌥A or /approvals reopens it, as for an
approval. Enter on an item opens its first file through offered_file; ← →
step between files, ↑ ↓ and PageUp/PageDown scroll, and Esc returns to the
list with its choices kept. The source view keeps the Offer top row, then
shows the item's kind, name, path and file number above its full text,
wrapped without highlighting or line numbers; while waiting it shows
"Loading…", on refusal the message, and for empty text "(empty file)".
The source view closes on reconnect; replay shows the offer list.
The view's top row names it "Offer", with "repository code" dim. Each item
is a row naming its kind and name with what identifies it ("Extension notes ·
v0.3", "Hook tidy · before_tool on read, shell", "MCP server linear ·
declared in .fiber/mcp.json"), "▸ " in secondary and the row in
secondary on the chosen item. Under it, dim, what an install shows: where
it comes from and where it loads, what it runs, and what it carries. A
changed item says "the declaration changed", dim, then its diff drawn as
"Changed files" draws a hunk. Last comes the item's choices on one row:
"( ) approve", "( ) skip for this session" and "( ) never", the chosen one's
mark "(•)" in secondary and its label bold, the other marks dim. After the
items, "A package's TUI files are never installed from a repository." and
the hint "↑↓ choose an item · ←→ its answer · Send answers them all · Esc
puts it aside", both dim.
The session list
Home lists every project, in the rail's order: the launch project first, then
the others in the order their first session started. Each project is a
section, and the sections scroll when they outgrow the screen. When the
list is one row tall, it shows the focused row's first line.
The section's header is the project's name, bold in the accent colour,
and a "+" that starts a session in that project, as on the rail; then, dim,
"N live · $spend", the count and summed spend of its live sessions; then
"N waiting on you" in attention when any wait.
Each live session is two rows, in the order the sessions started, as
the rail's cards are. The first row: "⌥N", the card's number, dim; the state
glyph ("State glyphs"); and the name, or the first prompt when it has none;
then, at the right end, the state's word in its colour and how long the
session has been in that state, dim, in the rail's units. The second row,
indented and dim: the id, the turns, a ⎇ and the branch, the spend and the
context percentage, joined by " · "; then, in attention, what it waits
on, in full: "approval: shell cargo publish --dry-run", "question: 2 of 3
answered".
A session closing after /clear stays a live row, its word "CLOSING",
dim, until it exits ("Slash commands"). The row gets that state from
session_status.closing.
The project's exited sessions follow under a dim "exited · N": up to
three, the most recent first, each one dim row: ○, the name, and at the
right the id, turns, spend and age ("3h ago"). A session that moved
workspace appears like any other exited session. When there are more, a
last row reads "… N more", and Enter or a click on it lists
the rest of the project's exited sessions in place.
The project's archived sessions sit under a dim "archived · N" after
its exited rows, folded. Enter or a click on that line lists them all in
place, paging the project's archived recent, the most recent first,
each drawn as an exited row, and again folds them.
The line is left out when N is 0. An archived session is on neither the
exited rows nor the rail ("Archiving" in docs/invocation.md).
The focused row is drawn on the selection bar. With no session, the list's
rows hold two dim lines, centred: "No sessions yet." and "Type below and
press Enter to start one."
Live sessions come from the hub's feed, across every project, grouped by the
project on each session_status. Exited sessions come from recent.jsonl,
then from the hub's paged query for older ones, grouped by the project on
each row.
Each project's "exited · N", "… N more" and the rail's "N ✓" count from the total of a recent scoped to that project, and "archived · N" from the total of one with archived. The terminal asks for them when the project first appears, after a reconnect, and when one of the project's sessions leaves, is deleted or is archived, with one ask of each in flight per project; it never adjusts a count itself. Until the first answer arrives, N counts the rows loaded. "… N more" counts the rows the hub holds past those shown, and opening it pages the project's recent.
Clicking a row, or Enter on it, opens the session: an exited one is resumed by
the hub. A session whose workspace is gone and cannot be made again opens
read only: the hub replays its log (docs/invocation.md, "Lifecycle"), and
the conversation shows as it would live, paging as any session does. A
one-row bar replaces the input box: " no longer exists. Read only.",
dim, with the path in attention. It adds no rail card, takes no prompt,
and Esc or ⌥0 go back home; the row stays where it was, archived or
exited. Opening an archived row resumes it the same way, which unarchives it. A ✕ on a live row stops that session ("Quit"). Delete on a
focused live row stops it too, after asking ("Quit"); on an unreadable row it does nothing, and with the link down it opens no question. Backspace never stops a session, whatever the row. A ✕ on an exited row, or Backspace on it, archives that session through the hub and asks nothing, since opening it undoes that. Backspace on a live, unreadable or archived row does nothing, and an archived row has no ✕. Delete or Shift+Backspace on a
selected exited or archived row deletes that session through the hub, after asking, and
the question names any session --cascade would add (docs/invocation.md,
"Deleting and pruning"). /delete deletes the session on screen instead:
it asks the hub for the exact sessions the delete would remove, asks the
person with those sessions named, stops every running one first, then
deletes that same set, which never changes after the question. Esc, a click
outside the frame or on its ✕ cancels and deletes nothing. It waits for fresh
exit evidence only for held sessions represented in the feed; a delegate
shuts down with its parent, and the hub's exact-set session_held refusal is
the backstop. A stop the hub refuses deletes nothing and names the session
still running; a stop with no answer shows Stop status unknown. A delete
refused because a session is running again keeps the attached session with a
Not deleted notice and does not retry; any other post-stop refusal returns
home with its stopped rows and the hub's message. /archive archives the
session on screen: it stops that session the way /delete does, with the
delegates that shut down with it, and waits for the same exit evidence, then
archives that one session and goes home. It asks nothing. A stop the hub
refuses archives nothing, with /delete's notices. A row whose status this terminal cannot read says CANNOT ATTACH and why: "Cannot attach: this session runs Fiber " when the hub runs another Fiber version or commit than this terminal, since a session runs the binary of the hub that started it, with <v> as fiber --version writes it; otherwise "Cannot attach: its status did not parse". Opening the row shows the same text as a session_held notice.
The mouse wheel over the list's rows scrolls the list by three rows,
leaving the focus where it is.
On exit
The terminal is restored and one line is printed per live session: its id and
the command to resume it.
Layout
The screen is a session rail on the left, a conversation column, and a side panel on the right. The conversation
column has no header row: its first row is conversation. The conversation keeps
one blank column on each side, so the turn cards start one column in from the
rail's edge and end one column before the panel's; with the rail hidden its
one-column grip sits at the screen's left edge and the cards start at the third
column. The panel is shown while the screen is wide enough, unless the person hides it with ⌥P. While
it shows, the input box leaves out its status line ("The narrow layout"),
and the input box spans only the conversation column.
The rail and the panel each take a share of the screen's width, kept between
a floor and a ceiling: the rail 15%, from 22 to 48 columns, and the panel 21%,
from 30 to 60. Dragging the edge between either and the conversation resizes
it, and saves the new share as tui.rail.width or tui.panel.width, so one
setting suits a laptop and a 4K screen alike. A drag stops where the
conversation would fall below its minimum width. Each draggable edge shows a
dim grip, ⋮ on three rows at mid-height; under the pointer, and while
dragging, the whole edge column takes the rule tint, the grip turns bold in
the accent colour, and the pointer becomes a resize arrow (OSC 22, where the
terminal supports it). The rail's and the panel's regions take the panel
tint from top to bottom. The numbers are starting values, to be tuned once the terminal
is built.
The rail
The rail lists every live session, across every project, as cards grouped
under project headers. The launch project's group comes first, then the
others in the order their first session started. The rail is drawn from the
hub's feed (docs/invocation.md, "The hub") and shows beside every session,
one session included, unless the person hides it. ⌥R and /rail show or hide
it and save the choice as tui.rail.shown, so a person who never wants the
rail sets it once. Home is the rail at full width ("Home").
← reaches the rail. In an empty input box, ← moves focus into the rail,
on the card of the session on screen; with text in the box, ← moves the
cursor. The focused card is lifted: its tint lifted, as hover draws it
("Mouse and hover"); with no colour it is bold and its box is not dim, while the other cards' boxes stay dim. The input box's stripe and text dim while the rail has
focus, and the foot hint reads "← full screen · ↑↓ move · Enter switch · Delete stop · → or
Esc back to the session · ⌥1–9 jump". ↑ and ↓ move between cards across the
project groups, Enter switches to the focused card's session, and → or Esc
gives focus back to the input box. Delete on a focused live card asks "Stop ?" over the conversation ("Quit"), with or without a draft in the box; the draft stays as it was. On a crashed or CANNOT ATTACH card, a project header's "+" or "N ✓" it does nothing. Typing on a focused rail goes to the draft and keeps the focus on the rail, and Backspace edits the draft and never stops a session; a key that types nothing, Delete by default, is what stops, and a key rebound to a character types it. A second ← widens the rail to home. When the session on screen has exited, its dim ○ EXITED card stays in place: the first ← focuses the card, and a second ← widens the rail to home with focus on that session's row under "exited". When
the rail is hidden, by the person or for width ("Shedding"), one ← from an
empty input box opens home.
A project header holds the project's name, bold in the accent colour, a "+"
that starts a session in that project, and, right-aligned and dim, the summed
spend of its live sessions and "N ✓", the count of its exited sessions, which
widens to home with focus on that project's first exited row.
Each card is four rows on its state's tint (the theme's card_* roles), inside ▄ and ▀ edges, with a ▌ stripe
on the left in the state's colour:
the card's number, the state glyph and its word, and how long the session
has been in that state, in one unit (16s, 9m, 2h, 3d)
the name, or the first prompt when it has none
what it waits on, in the attention colour, while it waits; otherwise a dim
⎇ and its git branch
its spend, a bar of how full its context is, and the percentage. The bar
fills with ▆ on a ░ track in rule; the fill turns the warning colour from
60% and the error colour from 85%.
Text on each side keeps the same margin from the card's edge. Below a 30-column
rail the bar goes and the spend and percentage stay. The session on screen
has a brighter tint than the others. Hover brightens a card and shows one
line at the rail's foot with the full name, workspace and model.
Cards keep the order their sessions started, and a card keeps its number
for its whole life: numbers never move when a session starts or stops waiting,
and a dismissed card leaves a gap. ⌥1 to ⌥9, or a click, switch the
conversation and the panel to that session, and the rail scrolls the card
into view; the mouse wheel scrolls the rail. ⌥A goes to the oldest request
waiting anywhere ("Bindings").
Delegates are not on the rail; the parent's panel shows them. Exited sessions
are not on the rail either; their project header counts them.
A session whose process died stays on the rail as a ✗ CRASHED card until the
person resumes it, by clicking the card, or dismisses it, with the ✕ that
replaces its time. Both go through the hub, so every client agrees (docs/invocation.md, "The hub").
A CANNOT ATTACH card has the same ✕ in its time's place. It hides the card in this terminal only, until the terminal exits, and sends nothing to the hub, whose dismiss drops only a crashed session (docs/invocation.md, "The hub"). The card comes back when the session's status can be read again or the session crashes.
State glyphs
The rail, home's session list and the terminal title use one set:
session_status
Glyph
Word
Colour
streaming, tool
a braille spinner, ● under reduced motion
WORKING
the accent
retrying
the spinner
RETRYING
warning
waiting
!
NEEDS INPUT
attention
idle
✓
READY
dim
the process died
✗
CRASHED
error
The spinners step on the working line's timer. A card that starts waiting
pulses its glyph and stripe for its first 10 seconds, then holds still, so a
screen with nothing working draws no frames; under reduced motion it never
pulses.
The panel
The panel is a column of cards. tui.panel.cards lists which cards show and
in what order. An extension widget (host.widget, docs/extensions.md) is
listed as "<extension>/<widget>", which places it. A widget the list does not
name shows after the listed cards, in the order widgets arrived. The panel
scrolls when its cards outgrow the screen. A mouse-wheel step moves it by three
rows; scrolling clamps at the top and bottom of the content.
The default cards, in order:
Session status: the working directory; the git branch; model and thinking level; a context bar that
fills toward the automatic compaction point, with a marker there; tokens, cache
hit rate, the time until the prompt cache resets, cost billed and cost on subscription, delegates included, against
budget.usd when one is set; output speed and turns; and one "tools" line naming any
MCP server that is down. Every number has a plain label that says what it
measures, such as "tokens in / out", "cache hits" or "output speed, last
reply", never a bare abbreviation. The branch slot, every figure row, the
context bar and the line under it are drawn from the session's first
frame. The branch slot stays blank until status supplies a branch name, and
remains blank outside a repository. A figure not known yet, such as the
speed before the first timed reply, shows a dim "—", so no row moves when
its data arrives. The bar is drawn empty with 17 cells
in rule and a dim "—" for context size until its figures are known. Zero is
shown as zero. "turns" counts every turn the session has started, the
running one included, as session_status counts them (docs/events.md).
Changed files: the five files with the most lines changed, and totals.
Delegates: one six-row card, running first, with finished delegates
folded and whole-entry scrolling. Detail rows retain each delegate's
spend after completion. The detailed Delegates rules below define the
fold, scrolling and cost cases.
Jobs: one line saying how many run, shown only while a job runs. A
click lists them, one row each.
Quota, from each provider's quota(), as /quota shows it
(docs/tools.md, "Provider quota"). A provider without one shows none.
Each card is a surface slab on the panel's tint, edged ▄ and ▀ in the
surface colour over the panel colour, with two columns of padding on the
left, one on the right, and a blank row after it. Its title row holds the
card's name in bold, with a figure right-aligned. A value right-aligned on a
row is pushed to the card's right padding, and a row too long for the card is
cut with "…". The cards draw:
Session status auto
~/work/fiber
git main
anthropic/claude-opus high ∴
▆▆▆▆▆▆▆▆▆▆▆▆▆▆▆▆▆│ 268k
compacts at 400k 26% of window
tokens in / out 412k / 18.2k
cache hits 91%
cache resets in 42m
cost $4.12
cost on subscription $0.00
speed, last reply 64 tokens/s
turns 12
tools 31 ✗ github down
Changed files 7
…/tests/serve_attach.rs +120 −14
crates/tui/src/app.rs +38 −9
… 2 more +175 −83
Delegates 1 running
● review: the diff
14 calls · 2m 10s · $0.42 · read app.rs
1 finished ▾
✓ docs check
6 calls · 48s · $1.10 sub · done
Jobs 1 running ▸
Quota extension
claude weekly 65%
▆▆▆▆▆▆▆▆▆▆▆▆▆▆▆▆▆▆▆
Session status. The title is "Session status" in bold, with the
permission mode right-aligned in attention. Then the working directory;
"git" dim and the branch
in secondary; the model in accent, with the thinking level
right-aligned in attention and a dim "∴" after it while the model thinks.
The context bar is 17 cells of ▆, filled in info toward the compaction point
and rule for the rest, then the compaction marker, │ in attention, and the
context size right-aligned ("268k"). Under it, "compacts at 400k" dim, and
the share of the window right-aligned, dim. Clicking the bar or the line
under it opens the context breakdown. Each figure after that is a row: its plain label dim, and the
figure right-aligned in the text colour; a down MCP server is "✗
down" right-aligned in error. "cache resets in" is the time left before
the prompt cache expires, counted from the end of the last model request,
a warming refresh included, at the session's cache lifetime
(docs/prompt-cache.md, "Cache lifetime"). It shows "—" before the first
request and "expired" in attention once the lifetime has passed. It
counts in minutes, and in seconds under the last minute.
Changed files. The title's figure is the count of files, dim. Each row
is a path, cut from the left to keep its file name ("…/tests/x.rs"), with
"+N" in added and "−N" in removed right-aligned. The last row is
"… N more" dim, when there are more, and the totals.
Delegates. The title's figure is "N running", in attention while one
runs and dim otherwise. Running delegates come first. A dim N finished ▸
row folds every finished delegate by default; click or Enter opens it with
▾, listing finished delegates in start order. The state lasts for the
session. The card scrolls on its own under the mouse wheel: one delegate or
the fold row per step, and never half a delegate, within its six-row cap.
Opening or closing keeps the scroll position and clamps it to the last full
window. Each delegate has a spinner in attention while it runs ("●" when
still; "The working line") or "✓" in success once done, then its
description. Its second row shows calls and elapsed time, then known billed
and subscription costs, then its last step or outcome. Subscription cost is
dim and ends in sub. Positive billed and subscription totals both show,
both zero totals show $0.00, and unknown billed spend with zero
subscription spend shows no cost. A finished delegate keeps its last
reported spend. Spend comes from each delegate's session_status over a
summary connection.
Jobs. "N running" in attention while one runs, then a dim "▸".
Quota. "extension" dim in the title. Each limit is its name dim with
the share left right-aligned, and a bar of ▆ under it in accent, or in
error with the share when little is left. A window shows 100 - percent_used, floored at zero, as a rounded whole percent. A credit with
a positive limit shows remaining divided by limit, clamped to 0–100%.
The figure and bar use error at or past quota.notice_at percent used
(default 80). A reset window says "reset" with a full accent bar.
A credit without a positive limit shows remaining to two decimals, with
no bar or error colour. The bar fills to the share left, rounded to
the nearest cell, with at least one cell for any positive share.
Each name is the provider and window name, or "credit". The credential
label follows the provider only when it has more than one label.
An unreachable label shows its last value without age, or nothing when
it has none. With no rows, the card draws nothing.
The terminal asks for cached quota on attach, on focus-in (DEC mode
1004), and at each attached session's busy-to-settled turn end. A
keypress asks only once the last answer is at least 5 minutes old
(docs/tools.md, "Fetching"). At most one query is in flight; a turn
end during it is not held. A rejection stops queries until reattach.
With the rail hidden and sessions waiting, the Session status card ends with "! N
waiting · hidden · show" in attention, the "!" bold; a click on it
shows the rail.
While a Fiber delegate's view is open the Session status card follows
that delegate's figures: its title reads "◆ ", from the
open job record, and every figure below it reads the delegate's own
session_status, preamble_built, model_changed, turn_completed
and usage_recorded lines. A value the delegate has not sent yet reads
the unknown form above for it — a blank workspace, model and branch, an
empty bar, dim dashes — never the attached session's. A finished
delegate's view keeps its last status, every row dim, with the items
outcome (completed, failed or cancelled) beside the permission
mode; without a stored status it shows the delegate's calls and elapsed
time instead. Esc returns the card to the attached session.
The context bar is drawn against the window session_status reports and
the compaction point the session's own preamble_built names. That window is
the latest own build's context_window, or the inherited one when the
session logged no preamble_built of its own. A session started by a
rewind, a fork or a workspace change has no compaction point of its own, so
its bar draws against the inherited window with no marker. Per-file counts
come from tool_call_completed's changes,
never from details, which has no fixed shape a client may rely on
(docs/events.md).
⌥P shows and hides the panel. Every panel item is clickable and opens its view: the model picker, the
context breakdown, usage, the tools, a delegate's or job's transcript, or a
file's diff, or the quota view. The same views back /model, /context, /usage, /tools, /quota and /diff.
There is no built-in task list
(Task list).
An extension's widget can supply one.
Running tool calls show in the conversation, on the live group's line, not in
the panel.
Git
The branch and status come from the person's shell command
(docs/invocation.md, shell): git --no-optional-locks status when the
person clicks for it, and git rev-parse --abbrev-ref HEAD on attach and
after each turn. Nothing polls. A rail card's branch comes instead from that
session's session_status (docs/events.md), which the session updates when
it starts and after each turn.
Swapped views
A remote terminal's configuration views show the hub's machine: its
settings, rules, credentials, tool switches and skill switches and text.
keys and every tui.* key belong to the client instead, including /keys,
their /settings rows and the theme picker.
For a hub-owned file, Ctrl+G fetches its text and opens a temporary copy in
the client's editor. On return, the hub writes it only if its version still
matches. Otherwise the view says the file changed and nothing is written.
The view then rereads the hub's file, showing any configuration or rules
error just as it does after a local edit. The Ctrl+G sentences of /rules,
/settings and /skills in the list below describe the local editor; this
paragraph replaces them on a remote terminal.
A view whose rows take Enter or a switch marks the focused row with "› " in a
two-column gutter, as overlay choices do, without the bar.
Every swapped view and overlay keeps the same controls, from the #4280
design:
Esc is named once. A swapped view names it in its top row, "Esc
returns", or "Esc back" on a sub-page, and its footer leaves it out. An
overlay has no top row, so its footer ends "Esc close".
The main action on the focused row is Enter, and Space does the same,
except in an approval, where Space does nothing. An approval takes the
keyboard as it opens, so a space meant for the input box would otherwise
approve the call. Delete removes or resets the row; Backspace is a synonym only where no
text field is open.
A footer names every key the view takes, keys bold and words dim,
joined by " · ", on the last row. A view that takes only ↑↓ and Esc has
no footer.
An empty state is one sentence in sentence case with a full stop,
followed by how to add the first entry where the view can add one ("No
rules yet. Rules appear when you allow a call always.").
A click on a row does what Enter does on it.
Moving past the end wraps. ↓ on the last row focuses the first, ↑ on
the first focuses the last, and ←→ across tabs wrap the same way.
A view swaps into the conversation area and takes all of it. Esc returns to
the conversation. Its top row, on the surface tint, is the view's name
bold, its command dim (" /context"), and "Esc returns" dim, right-aligned;
a click on it returns too. The mouse wheel over a view moves its visible rows 3 a step and never the conversation under it. The views are:
A delegate's or job's view. Its header is a breadcrumb
("main › ◆ review: …"). A status card gives harness, model, calls, elapsed
time and session, with a stop target. The transcript uses the same turn
cards as the conversation, and the input box sends steering messages to
that delegate. The breadcrumb is bold. The status card is a surface
slab: "harness ", then " · model · " dim; under it,
dim, the calls, "elapsed
While a Fiber delegate's view is open, the Session status card, the
input box's status row and the status line's cost and cache segments
follow that delegate's figures; changed files, Delegates, Jobs and Quota
keep the attached session's. A value the delegate has not sent yet reads
its unknown form there too, never the attached session's: a blank model
and branch, an empty context bar, dim dashes for the figures, and no
cost segment until its status lands. A finished delegate's card keeps
its last status, dim, with the outcome beside the permission mode;
without a stored status it shows the delegate's calls and elapsed time
instead.
A job running under a pseudo-terminal has a live view of its screen. The
input box sends job_input to type into it as raw keys, as jobs write
does for the model, so the person can finish an interactive step the model
started. Esc, Ctrl+C and Ctrl+L keep their meanings there (closing the view,
clear then quit, the model picker), so they are not typed into the job; the
status card's stop target ends it. The screen is
80 columns by 24 rows, drawn from the job's output since the terminal
attached. Carriage return, line feed, backspace, tab, cursor movement and
erasing in a line or the display are applied; other escape sequences are
dropped. Its status row is "job · · running
The running delegates or jobs, from "N delegates running" or "N jobs
running" in the narrow layout: two rows for each delegate, or one row for
each job, in the order they started. /jobs (/tasks and /ps run the
same command) opens the jobs list. A row opens that item's view.
"Delegates · N running" bold heads the delegates. A delegate's first row is
"◆ · "; its second, indented two columns, is dim:
the model, the thinking level, the calls and the session, then its spend,
a 10-cell bar of how full its context is and the percentage. The bar is ▆
in accent for the share used and in rule for the rest, the fill turning
the warning colour from 60% and the error colour from 85%, as a rail
card's does. "Jobs · N running" bold heads the jobs, one row each: "◆
· · ". The last row is "a row opens that item's
view", dim.
Every delegate, from /delegates (/agents runs the same
command): running delegates in the order they started first, then
finished ones in the order they started, two rows for each delegate
in the Delegates card's format. A row opens that item's view; a
finished row opens its replay. The top row is Delegates with
/delegates dim; there is no heading row and no count. With no
delegates the view says "No delegates".
The model picker
Models by provider with roles marked, a chip for each
thinking level the model supports, each model's input and output prices,
and what a switch to it costs to rebuild the prompt cache. Choosing a model
saves the global model, and choosing a level saves models."<provider/model>".thinking to the global file. On a remote terminal it lists the hub's catalogue, the models the hub's machine can reach (docs/invocation.md, "What the hub speaks", models), and a session started from it runs on the hub. Ctrl+S
marks the choice as this session only, and then nothing is saved. A choice
sent while a turn runs says it applies when the turn ends: the chips hold
the old model and level until the session accepts it, and the choice
applies at the turn's end. The notice appears when the choice is sent; if
the session rejects the choice, the rejection's notice replaces it. When
scoped_models is set, the picker shows only those models, with a "show
all" toggle on Tab. A provider hidden by scoped_models has no section and no count row, and does not by itself make the picker show "No models match". Typing filters the list on every letter: each
space-separated word of the query must match, in order but not
necessarily next to each other and ignoring case, the model's provider,
id or display name. A left-out count row matches the same way, against
each left-out model's provider, id or display name, and shows only the
matched count; no row shows when none matches. The filter keeps the
list's order and only drops rows. Backspace removes a letter; Esc clears the query first and closes
the picker on the next press. Enter with nothing focused does nothing and
leaves the picker open; it installs only a row ↓ or a click has focused.
Ctrl+L opens it, as /model does. It draws from the cached
model lists at once and refreshes stale ones in the background; its refresh
button refreshes every list (docs/model-routing.md, "Model discovery").
The mouse wheel over the list scrolls it 3 displayed rows a step, counting headings, count rows and blank rows. A step that scrolls the focused row out of view moves the focus to the nearest focusable row still in view, the upper one on a tie; with no focusable row in view, the focus stays where it is. On a screen too short for two list rows, when there is no model for the list to keep, the list drops a provider's left-out count row together with its heading and separator, so a count never shows without its provider.
Under the view's top row the picker is an overlay ("Look", "Overlays").
Its first row is the filter: "Type to search" dim until something is
typed, then "›" dim and the query bold, with the cursor ("The input box") either
way. Its second row holds the count dim ("12 models", "scoped · 5 of 12"
under scoped_models, or "4 of 12 models" while a query is typed), then "[show all]" bold, which reads "[show scoped]"
while every model shows, and "⟳ refresh all" dim at the right end. These
counts include models only, not logged-out or not-installed provider rows.
Each provider is a section, a blank row between them: the provider's name dim,
then "· updated 2m ago" dim, or "⟳ refreshing" and a spinner in
attention while its list refreshes. In the choosing picker, a provider
with models left out for a placeholder with no value shows one count row
after its heading and before its models, indented four columns and
uniformly dim: "2 models need workspace: run fiber login acme", or "1
model needs api_key: set it in config/acme-ext.json" naming the supplied
file when the provider's data declares a credential_label. The row never
focuses and takes no clicks; it shows under "show all" too, and never in
/thinking or /scoped-models. Under scoped_models with "show all"
off, a provider with no scoped installed model shows no section and no
count row. Each model takes two rows. The first
is the model's id in accent, each role dim in brackets ("[reviewer]"),
"● current" bold in accent on the session's model, "· scoped" dim on a
scoped model while every model shows, "· new" dim on a model its vendor lists
that Fiber has no details for (docs/model-routing.md, "Which models exist,
and what Fiber knows about them"), then its input and output prices per
million tokens dim ("$3.00 in · $15.00 out /M"): "free" when both are zero,
and nothing for a model whose provider data names no cost. A model priced
by request size shows the prices of the tier the session's last call falls
in, with the tier's threshold ("$6.00 in · $30.00 out /M · tier 200k+";
docs/model-routing.md, "Cost"), and its base prices before the session's
first call. On a screen too narrow for 60 columns inside the picker, the
prices are left out. Once the session has made a call, the switch cost is
dim at the right end: the prompt-cache rebuild a switch to that model costs
at its rebuild price ("switch ~84k tokens · $0.31", "switch ~250k · $1.88"
at a tier's price, "switch ~58k tokens" for a model with no price, "—" for
the current model). On home and before the session's first call, no row
shows a switch cost. The second,
indented four columns, is "thinking" dim and the model's levels, or "fixed
thinking" dim for a model with none. On the focused model the levels are in
attention, its saved level bold, and the chosen chip bold in brackets
("[high]"); elsewhere they are dim. ← and → move between the focused
model's chips. A model chosen for this session only gets a third row,
"ⓢ this session only · nothing saved" dim. While a query is typed, the
characters of each id it matched are underlined and bold. If no model, count
row, logged-out row or not-installed row matches, the picker shows one dim line,
"No models match", and no provider sections. The footer is "↑↓ move · ←→ levels · Enter choose · Tab show all ·
Ctrl+S session · Ctrl+R refresh · Esc close", keys bold. Its Tab entry
names what Tab does next, as the count row's toggle does: "Tab show all"
while only scoped models show, "Tab show scoped" while every model shows,
and no Tab entry when scoped_models is unset.
On a screen too short for every row, the list scrolls in the rows left
between the count row and the footer, and it always shows at least one
model with its provider's heading: the session's model when the picker
opens, the focused model after ↓ or a click. Where even that does not fit,
the list keeps it and the footer goes first.
After the model sections and their left-out count rows, the choosing picker
lists each installed provider with provider data but no credential, one row
per provider in provider-name order. It never lists the scripted provider.
When model sections precede these rows, a blank row separates them. A
login-capable provider's row shows the gutter, its name in accent, and
" · not logged in" dim. Enter or clicking its name closes the picker and
opens /login with that provider focused. After a successful login, the
provider's models appear the next time you open the picker. A provider with
a credential_label instead shows its declared environment variables or
file paths in a dim suffix, such as " · set AWS_ACCESS_KEY_ID to log in".
Enter or clicking its name sends nothing. The row still takes focus. These rows
appear only in the choosing picker, before not-installed rows. Typing filters
them by provider name.
After any logged-out rows, the choosing picker lists each first-party provider no installed extension declares, one row
each (docs/extensions.md, "A fresh install"): the gutter, the name in
accent, " · not installed" dim. When other list rows precede them, a
blank row separates them. The scripted provider is never listed
(docs/model-routing.md, "The scripted provider"), and /thinking and
/scoped-models list neither group. Typing filters these rows by provider
name as it filters models. "Show all" leaves both row groups as they are.
↑ and ↓ walk models, logged-out providers and then these rows; no row is
focused until ↓ or a click puts it there, so Enter with no row focused does
what it does with none
listed (a query that hides every model focuses nothing). The focused row
reads as a focused model does, with "› " in its gutter, bold, on the bar.
Enter, or a click on the name, installs the provider as fiber extension install <name> does, asking nothing more: choosing the row is the approval.
While it installs the row reads " ⟳ installing" and the spinner in
attention; choosing another row does nothing until it ends, and closing the
picker does not stop it. A failed install keeps the row, still marked not
installed, and adds a row under it, indented four columns, "✗ " and the
error in error, its first line cut at 80 columns; choosing the row again
tries again. A successful install drops the row, asks one model refresh so
the provider's models list, and draws under the list, until the picker closes
and indented four columns: "✓ " in success and "installed ", the
lines of the install summary dim ("What an install shows",
docs/extensions.md), and, for a provider whose key is missing, "
needs a credential: run fiber login <name>" dim, or, for a key that could
not be read, "✗ 's credential could not be read: " in error.
An install that ends while the picker is closed asks the refresh and, if it
failed, shows the notice "Installing failed: "; if it
succeeded, each credential line above is a notice instead
(credential_missing, credential_failed). On a remote terminal the install
runs on the hub (docs/invocation.md, configure, install_provider) and
the list is the hub's; with the hub not connected the row fails with "The hub
is not connected."; and the install holds the terminal's one hub connection
until it ends, up to 1,800 s for each install step (docs/extensions.md,
"Installing"), so other hub commands wait behind it; while it runs on a
remote terminal, /settings and the other config views are refused with "a
provider is installing; try again when it finishes" (a local terminal gets
no such refusal), and on either terminal Esc closes the picker with the
install still running.
The credential picker, /credential: the header reads "Credentials" bold,
" /credential" dim and "Esc returns" dim, right-aligned. The provider's
labels follow the header in the answer's order,
one per row. Only the current label has " ● current" in accent after
it and starts selected in reverse. With no current label, the first row
starts selected. The plain line above the bottom footer reads the provider's name, such as
"fake", or "Reading the labels…" before the answer, or
" has no credential labels" for an empty answer. A rejected
query shows its message instead. The dim footer on the last row is
"↑↓ move · Enter choose · Ctrl+S this session · Esc close".
↑ and ↓ move between rows. Enter or a click chooses a label and saves
it; Ctrl+S, session_only's key, chooses it for this session only.
Esc closes. Typing does nothing: there is no filter. Choosing from an
empty list does nothing. A session-only choice adds no extra row.
The usage view,/usage: the session's usage (docs/events.md) broken
down by turn, by model and by delegate, each with tokens by kind, cost billed
and cost on subscription, and the budget left when budget.usd is set.
"By turn", "By model" and "By delegate" are bold headings, then one row
each: "turn 3 · 120k in · 15k out · $1.35 billed · $0.00 subscription".
The last row is "budget left $17.90 of $20.00", dim.
The quota view,/quota: one row per entry of the quota answer
(docs/events.md), in its order, with the same name, figure and bar as
the panel card. The top row reads "Quota" bold, " /quota" dim and
"Esc returns" dim, right-aligned. Each window's reset time follows its
bar, dim ("resets in 3h12m"). An unreachable entry shows its last value
and "unreachable" in error, or "unreachable" alone when it has no
last value. With no entries, one dim line reads "No provider reports
quota". While the fetch is in flight, the top row shows "fetching" dim.
Opening the view sends quota with fetch: true.
The view draws the cached answer at once and redraws on the fetch's
answer, which also updates the panel card.
The status view,/status: what the terminal already holds about the
session on screen, asking nothing. The top row reads "Status" bold, " /status"
dim and "Esc returns" dim, right-aligned. Each row is a name dim, padded to
one column, then the value:
"session": the session's id, then " · " and its name;
"workspace": its workspace, then " · branch " and the branch in a git
repository, or " · detached" when HEAD is detached;
"model": the model, then " · thinking " and the level when it has one;
"credential": the label the session's requests use, or "none" when its
provider takes no credential;
"permissions": "auto", the one mode (docs/permissions.md, "One mode");
"hub": "this machine", or the listed hub's name on a remote terminal;
"version": Fiber's version;
"context": the context's size and the model's window, "268k of 1M
tokens";
"turns": "3 turns · 12 calls", or the calls alone when the session
reports no turn count;
"clients": the full connections attached.
The session's rows come from its latest session_status, and "credential"
from its latest preamble_built or model_changed (docs/events.md); a
value not received yet reads "not known yet", dim. The view redraws as
they change.
The doctor view,/doctor: the report fiber doctor prints
(docs/invocation.md, "Commands and flags"), captured when the view
opens and shown one plain row per line, from the same code that prints
it, so the two never differ. The top row reads "Doctor" bold,
" /doctor" dim and "Esc returns" dim, right-aligned. ↑ ↓ and
PageUp/PageDown scroll; Esc or a click on the top row returns to the
conversation. The report is captured in the terminal's own process, so
on a remote terminal it describes the client machine, not the hub.
When the capture fails, a notice says so and no view opens.
The context breakdown: one bar of context by category against the
compaction point, with the largest tool results. The categories are the
system prompt, tool definitions, tool results since the compaction in force,
and messages, which takes the rest of the session's context total. Each
of the first three is estimated from its bytes at the session's own
tokens-per-byte rate, and the view says the sizes are approximate.
Until a request gives a rate, and when the session logged no
preamble_built of its own, it shows the total alone. After attaching,
the terminal uses context totals and windows only from that session's
session_status, and uses that status's reported window when there is
no own preamble; it does not reuse the previous session's context. A
session_started also clears preamble-derived category estimates, so a
fork cannot reuse its parent's. Largest results stay in bytes until this
session has its own first-request rate; the view never reuses a prior
session's rate. It is drawn indented two columns: "268k tokens" bold,
then " · 26% of the 1M window · automatic compaction at 400k" dim; the bar,
one █ run per category in its colour, ▁ in rule for the room left, and │
in attention at the compaction
point, with "compaction 400k" in attention right-aligned under the marker;
one row per category, "■ " in its colour, the name padded to 20 columns,
the size and its share dim; then "Largest tool results" bold, one row
each, what it was dim and its size; and the note that sizes are
approximate, dim. Each category has its own colour; tool results are
error.
Changed files: the files Fiber changed, grouped by folder, with the
chosen file's hunks. The hunks are the workspace's current diff against
HEAD, read when the file is chosen, so they include changes Fiber did
not make; the row under the top row says "N files · diff against HEAD",
dim.
Folders: paths are relative to the workspace. Each folder holding a
listed file is one dim row ("delegate/src/session/"), in path order,
and its files follow it, indented four columns, in name order. A file
at the workspace's top level sits under a "./" row.
A file's row: a letter, then the file name bold, then "+N" in
added and "−N" in removed, right-aligned in one column. The letter
is M in attention for a changed file, A in added for a new or
untracked one, and D in removed for a deleted one. An untracked file
counts its lines as added. The focused row takes "› " in accent in
the gutter and its file name bold in accent ("Swapped views").
A file with no diff: a file Fiber changed whose diff against
HEAD is now empty, because its change was committed or undone, stays
listed, its row dim: "·" for the letter and "no changes" where the
figures go. Chosen, it shows "No changes against HEAD: committed or
undone since Fiber changed it.", dim, and no hunks.
Totals: after the last file, a rule line, then "N files" dim and
the summed "+N" and "−N" in the figures' column.
Figures: a row's figures are git's for that path, so they match its
hunks: one git diff --numstat HEAD limited to the listed paths, run
when the view opens, and, for a path git does not track, its line
count as added. Until that answers, the rows show the Changed files
card's figures, which sum Fiber's own edits (docs/tools.md, "write"
and "edit").
Hunks: under the chosen file's row, its path bold, then "Open in
editor ›" in secondary, right-aligned, then its hunks in the diff
format an opened edit uses ("Tool groups and the ledger"), with git's
three lines of context.
Open in editor: a click on "Open in editor ›", or Ctrl+G, opens the
chosen file in the editor ("The editor") at +N, where N is the first
line of its first hunk, or 1 when there is no hunk. The editor gets the
whole screen, as Ctrl+G on the draft does. On return, the view reads
the file's diff and numstat again. On a remote terminal it fetches the
hub file at the session's workspace and opens a temporary copy at the
same line, and on return writes the copy back only while the hub file
still has the fetched version. A hub-side edit in between leaves the
file unwritten with the changed-file notice, and the view still reads
the diff and numstat again.
Footer: "↑↓ file · Ctrl+G open in editor", with the keys bold.
Changed files /diff Esc returns
4 files · diff against HEAD
delegate/src/session/
M supervisor.rs +121 −7
M state.rs +62 −6
delegate/tests/
› M session_engine.rs +148 −3
delegate/tests/support/
A muse_host_fake.py +15 −3
────────────────────────────────────────────────────────────────────
4 files +346 −19
The release notes,/release-notes: the running binary's
changelog section for its own version (docs/releasing.md, "The
changelog"), embedded in the binary at build time, so the view asks
nothing and opens with no session on screen. The section is the one
headed by exactly ## <version>; a version with no section shows "No
notes for this version." with the releases page instead. The top row
reads "Release notes" bold, " /release-notes" dim and "Esc returns"
dim, right-aligned. A bullet is "• " in accent, its wrapped lines
hanging two columns in; other long lines wrap at the width.
A call's view, from an opened call: the whole call, drawn as it is
inline ("Tool groups and the ledger") with no 20-line cap. The top row is
the call's kind capitalised, bold, then its target dim ("Shell cargo test
-p log"). When the result has an artifact, the view pages the whole
saved output from the session with artifact_page
(docs/invocation.md, "What each command does"), as the conversation
pages history, and never loads the file whole. A page that fails to load
leaves the view open with the pages it holds and a notice; scrolling to it
asks again. A dim marker sits at each
edge of the model's view, from the result's kept: "── end of the
model's view ──" where it stops and "── the model's view resumes ──" where
it resumes. A result cut at one end only has the one marker. The view
scrolls as the conversation does, y copies the whole call, and search
("Search") matches inside the view only. The last row is "y copies the
whole call", dim. Esc returns to the conversation with the call's row
still focused.
Search results: every match with its surrounding lines ("Search").
The first row is "3 of 5 · ⌕ ". Each match is the lines around it
under a row with the file of the tool call it sits in, ending in turn N,
dim and right-aligned. A match with no such file has turn N alone.
The match is on the match tint and the
current match on match_current. The last row is "Enter jumps to the
match", dim.
The tools view,/tools (docs/tools.md, "Seeing the tools"): every
tool by source, full or deferred, and its approximate size. Each MCP
server's or extension's tool has two on/off switches, this project and
everywhere, that write that source's tools.enabled and tools.disabled
in the project's or the global file (docs/configuration.md). A change takes effect on
reload, and the view says what the reload's cache rebuild costs. Built-in
tools have no switch: they are always declared, so every session sends the
same tool list, and the view shows them as rows without a switch.
Each source is a bold heading ("Built-in", "MCP · linear", "Extension ·
notes"), then one row per tool: " · full · ~1.2k", or "deferred",
then " · this project " and its switch and " · everywhere " and its switch.
A switch reads "[on]" bold or "[off]" dim. On the focused row, a bold "›"
marks the focused switch, and ← and → move it between the two. The mark
takes the place of the space before the switch, so columns do not move. It
shows on the focused row only. The last row is "a change rebuilds the
cache (~84k tokens · $0.31) on reload", dim.
The hooks view,/hooks: one row per hook and watcher the session
registered, hooks first in hook-point table order and run order, then
watchers in registration order. One row per hook: its source (the declared
entry's name, else the extension's name), its point, and blocking or
non-blocking; one row per watcher: its source, its kinds joined with
", ", and watcher. With none registered, it says No hooks.
The MCP view,/mcp: one row per configured server: its name, where it
is declared (global, project or this repository), its state and its
tool count. The state is not started for a server never started this
session, ready for a running one, failed with the hub's
mcp_server_failed sentence, or needs-login. A failed row is in
error, a needs-login row in attention, a not-started row dim, a ready
row in the text colour. Enter on a failed server reconnects that one
server; Enter on one that needs a login runs the login fiber mcp login
runs (docs/mcp.md, "What Fiber does with MCP"): it opens the browser
and waits for the loopback callback, and the row shows the wait with the
login URL cut to fit, then success or the failure reason. Enter on a ready
or not-started row does nothing. A repository's server nobody approved
shows not approved, and Enter says to run fiber approve in the repository;
the view never approves it. Rows sort by server name. The last row is
"Per-tool on/off switches stay in /tools.", dim. On a remote terminal
the browser opens on the hub's machine, so the row's URL is the one to
open by hand.
/rules: every standing rule by scope, global and then this project.
Each shows the prefix it allows, when and from which session it was added,
and a ✕ that revokes it. Revoking deletes the line and applies to the next
call judged. Ctrl+G opens the rules file (docs/permissions.md,
"Remembering a decision"); on a remote terminal it opens the hub's file
instead ("Swapped views"). "Global" and "This project" are bold headings;
a rule's row is "allow shell:git status · added 2d ago in review #688 · "
and the ✕ in error. The last row is "Ctrl+G opens the rules file", dim.
/settings: every configuration key with no * in its path, sorted
into tabs by what it is for, except hub.port, which fiber config set
and fiber hub install --port write. The design is from #4280, and
docs/mockups/settings.html is a clickable mockup of it. The mockup's
values are made up; this section is the authority. No row takes typed
text where its valid values can be listed or bounded.
Top rows: the view's name row, then "Changes save automatically",
dim, then the tab bar: Appearance, Notifications, Models, Permissions,
Sessions, Advanced. The open tab is bold on an accent fill with the
background colour for its text; the other tabs are dim. ←→ moves
between tabs and wraps from the last tab to the first and back. The
view opens on Appearance.
Tabs: each key with no * in its path belongs to exactly one tab,
named in its KEYS entry, unless a screen row covers it: then that row
draws it, and the key has no row of its own. Every KEYS entry has a
label and a one-line description. The screen rows are not KEYS
entries; each has its own label, one-line description and tab. A test
fails when an entry lacks its label or description, when a key with no
* lacks its tab and no screen row covers it, or when a screen row
lacks any of the three. Advanced holds what a person rarely
changes (hub.*, session.idle_exit_ms, cache.*, retry.*,
diagnostics.level). Permissions holds the reviewer keys first, then
the sandbox keys.
Rows: each row is the key's label, then its value, spaced one blank
line apart on terminals tall enough. ↑↓ move between rows and wrap
from the last row to the first and back.
The focused row's "› " and label are bold in accent. Other labels
are plain.
A value is in info, bold on the focused row. An unset value reads
"Default", dim. Every number shows its unit: "30 min", "$10",
"400k tokens", "80% used".
A value set anywhere but global is followed by its layer in
attention (project, repository, -c); a global or default
value shows no layer.
A key with * in its path has no row of its own. Eight rows open a
screen or start a skill instead: Key bindings (/keys), Scoped
models (/scoped-models), Credentials (/credential), Rules
(/rules), Tools (/tools), Reviewer notes (/reviewer-setup),
Skills (/skills) and MCP servers (/mcp). Such a row's value is in
secondary: "Open /keys ›", or a count where the screen keeps one
("All models ›", "3 models ›", "2 off ›"). Key bindings ends
Appearance; Scoped models then Credentials end Models; Reviewer
notes, Rules then Tools end Permissions; and Skills then MCP servers
end Sessions. Scoped models covers scoped_models, Reviewer notes
covers reviewer.context and Skills covers skills.disabled.
Reviewer notes reads "Edit with /reviewer-setup ›", with the notes'
first line dim under it, or "None yet" dim. Enter on it, or on
Credentials, closes /settings and runs the command in the session
on screen. On home, with no session, it first starts a session in
the current directory, then runs the command there.
Controls: Enter or Space changes the focused value, by its type.
A boolean shows [x] On in added or [ ] Off dim, and the key
flips it.
A key with a fixed set of values (thinking, cache.lifetime,
diagnostics.level, tui.theme, tui.logo_glyph) steps to the
next value. For tui.theme, each step previews the theme live. An
unset key shows "Default"; the first step writes the first value,
and steps wrap in the schema's order. Delete returns it to unset.
A model reference ends in " ›" and opens the model picker; its
choice saves to the row's key.
A key whose valid values are known only at run time ends in " ›"
and opens a pick list of them, with "Default" first: installed search
backends for web_search.backend, the names under hubs for
hub.default, and the editors on PATH for tui.editor. Enter
picks and saves; Esc closes without a change.
The Editor row's pick list holds, after "Default", each of nvim,
vim, hx, nano, micro, emacs, code, cursor, zed and
subl found on PATH, then "Other…". code, cursor, zed and
subl save with --wait: without it they return at once, and
Ctrl+G on the draft would read the file back before any edit.
"Other…" opens a field for a command line, holding the current value;
Enter saves it and Esc cancels. An empty field saves as unset, so
the row returns to Default. "Default" names the variable the
editor rule picks and its value, "Default ($VISUAL: vim)" or
"Default ($EDITOR: nvim)", or reads "Default (none set)" dim when
neither is set.
A number with a natural range is a slider, ▕████░░░░▏ in info
followed by the value and its unit. ←→ on the focused row, and Enter,
move it one step; Enter steps up and wraps from the top of the range to the bottom.
Key
Range
Step
Shown as
tui.rail.width
10–40%
1
"15% of screen width · 33 columns"
tui.panel.width
15–45%
1
"21% of screen width · 46 columns"
quota.notice_at
50–95%
5
"80% used"
compaction.window_fraction
50–90%
5
"70% of the context window"
cache.warm_cap
0–11
1
"2 cache lifetimes"
retry.attempts
0–10
1
"3 retries"
An off-range slider fills or empties its bar at the bound it passes, arrows step to the nearest in-range tick in their direction (from above the maximum, ← lands on the maximum), and Enter steps up or, from above the maximum, wraps to the minimum.
The column count for a width is what the share gives on the current
screen, after the rail's 22–48 and the panel's 30–60 column limits.
A number with no natural top is a list of values that Enter steps
through, wrapping at the end; ←→ step back and forward.
Key
Values
compaction.tokens
100k, 200k, 400k, 600k, 800k, 1M tokens
budget.usd
No limit, $1, $5, $10, $25, $50, $100
reviewer.block_limits.consecutive
1, 2, 3, 5, 10 blocks
reviewer.block_limits.session
5, 10, 20, 50, 100 blocks
retry.initial_delay_ms
0.5 s, 1 s, 2 s, 5 s, 10 s
retry.max_delay_ms
10 s, 30 s, 1 min, 2 min, 5 min
hub.idle_exit_ms, session.idle_exit_ms
5 min, 15 min, 30 min, 1 h, 2 h
model_lists.refresh_after
1 h, 6 h, 12 h, 24 h, 3 d, 7 d
session.keep_exited
Keep all, 5, 10, 20, 50 sessions
Each list holds the key's default. A value a file sets that is not
in the list shows with "(custom)" after it, and the next step goes
to the nearest listed value in that direction.
tui.panel.cards ends in " ›" and opens a checklist of the panel's
cards and the installed extensions' widgets, in the panel's order,
the ticked ones first. Space ticks or unticks; ⌥↑ and ⌥↓ move a card
one place. Each change saves the list.
A list of paths or addresses (sandbox.allow_write,
sandbox.deny_read, repository_extensions, hub.allowed_origins)
ends in " ›" and opens a sub-page of its own, one list per screen,
titled with the key's label. It uses the controls /settings already
has and saves on every change.
Rows: one per entry, in order, then a last row "+ Add". An empty
list shows only "+ Add".
For a list of paths, Enter on "+ Add" opens a folder browser:
the sandbox lists start in the home directory and
repository_extensions in the repository, and cannot leave it.
↑↓ move, → opens the focused folder, ← goes up, and Enter picks
the focused folder. Only folders that exist are shown. Enter on an
entry opens the browser at that entry.
For hub.allowed_origins, Enter on "+ Add" opens a field with
"https://fiber.example.ts.net" dim in it as the example, and Enter
on an entry opens a field holding its text. The field refuses
anything but a scheme http or https, a host and an optional
port, with the error under it, before it saves. Esc cancels.
Delete removes the focused entry. ⌥↑ and ⌥↓ move it one place.
A repository_extensions entry shows its path as its text, then
[x] required or [ ] required. Space flips required. A new
entry starts with required off.
Each add, edit, remove, reorder or flip saves the whole list at once,
through the same path as fiber config set, to the layer the value
comes from (Saving). Nothing waits to be saved.
With no browser or field open, Esc returns to /settings with the
list row focused.
The footer is "Enter edit · Delete remove · ⌥↑⌥↓ move · Esc back",
with the keys bold.
Every change goes through the same path as fiber config set, which
checks its type.
Saving: a change saves at once to the layer the value already comes
from, or to global when no layer sets it. Tab moves the focused value
to the next layer the key allows (global, project, repository), and
Delete removes the override so the inherited value applies. On a
remote terminal, tui.* keys offer only the client's global layer. A
key set by -c for this run is read-only here: its row says where it
comes from ("set by -c for this run") and Enter, Tab and Delete do
nothing on it.
Under the list: the focused key's description, then its key path,
where it is set and when a change applies ("tui.reduced_motion · set
in global · Applies when the terminal starts again."), dim. After a
change, one more line says where it was saved ("Saved to repository
config.").
Search:/, or typing a letter, opens a search across every tab.
It matches labels and key paths, hides the tab bar and adds each
match's tab, dim, at the right. Esc clears the search. Deleting the
query to empty closes the search, as Esc does. Focus stays on the match
it was on, in that match's tab; with no match, it goes back
to the row focused when the search opened. A second Esc returns.
Footer: "←→ tab · / search · Enter change · Tab layer · Delete
reset", with the keys bold. Ctrl+G still opens the file; on a
remote terminal it opens the hub's file instead ("Swapped views").
Settings /settings Esc returns
Changes save automatically
Appearance Notifications Models Permissions Sessions Advanced
› Reviewer model gpt-6-luna ›
Blocks before asking you 3 blocks
Sandbox [x] On repository
Rules Open /rules ›
The model that reviews actions the agent wants to take.
reviewer.model · set in global · Applies at /reload (~4k tokens).
/keys: the rebinding screen ("Bindings").
/skills: one row per skill with its name, one-line description, where
it comes from (repo, personal, an extension by its bare name, or
built in; an extension named repo, personal or built in reads
extension <name>), whether the model can see it (seen or hidden),
and any skill it shadows, plus whether it is switched off. A switch turns
a skill off or on for this project or everywhere, writing
skills.disabled in that layer; the change reaches the model at the next
turn start. Enter shows the skill's text, after every skill it shadows
with its source and path, Ctrl+G opens its file
(docs/system-prompt.md, "Skills"); on a remote terminal it opens the
hub's copy instead ("Swapped views"). A row is "review · checks a diff
· repo · seen · this project " and its switch, then " · everywhere " and
its switch, as on /tools; a shadowing skill adds " · shadows ,
…" after the switches, cut with "…" so both switches stay whole.
Several shadowed sources list after one "shadows", separated by ", ",
most specific first (repo, personal, extensions by extension name, then
built in), each source once. An unresolved shadow path — no matching
skill entry, or an extension entry with no extension name — leaves out
the whole "shadows …" clause. When the row runs out of width
the description is cut first, then the name, then the skill's own source,
keeping room for " · shadows …"; the clause is left out only when the
fixed fields and both switches leave less than that minimum. The last row
is "Enter shows the text · Ctrl+G opens its file", dim.
/rewind ("Rewind").
/fork: rewinds to the end of the conversation ("Rewind").
A repository's offer, before a new session's first request ("Approving
what a repository ships").
The working line
The working line ("⠋ Working 11m 14s · Esc to interrupt") sits at the bottom of
the conversation, above the steering queue, not in the input box. It is
indented two columns: a braille spinner (⠋ ⠙ ⠹ ⠸ ⠼ ⠴ ⠦ ⠧ ⠇ ⠏) in
attention, "Working", then the elapsed time dim and " · Esc to interrupt"
dim, the hint only while nothing is open ("Keys").
A glimmer runs across its word: a band three cells wide sweeps left to right,
its centre bold in attention, its two sides in attention, the rest of the
word dim; it moves one cell a tick and rests for a few ticks past the word's
end. The spinners on a running group's
line and on running delegates spin on the same tick, about every 120 ms. While
a turn runs they cost nothing extra, since the frame is drawn anyway. While
only delegates run, the tick keeps running for their spinners. Under reduced
motion the word and the spinners stay still: the spinner is a ● and the word
is plain.
While Fiber waits to retry a failed model call, the working line says so:
"↻ Retrying in 4s · rate_limited · attempt 2 of 4".
The narrow layout
The conversation has a minimum width of 84 columns. Below it the panel goes away, and rows
under the conversation take its place. From the top:
the working line
the running delegates, up to 4 rows, while the conversation keeps at least
half the screen; otherwise they collapse into the status line
the steering queue
an extension widget row, collapsed to one line, which a click expands
the input box, with its status line
The status line is two rows at the bottom of the input box, under its
status row ("The input box"). It shows whenever the panel does not: in the
narrow layout, and on a wide screen with the panel hidden by ⌥P, /panel or
the rail. Each card contributes its segments to the status line in the configured order,
and each row is cut at the terminal's right edge. The
second row opens with "N delegates running" and "N jobs running", so they are
never cut; each opens a list of delegate or job cards in the conversation
area. Clicking any other segment opens its card's view, the Quota segment the quota view.
The status line sits on the slab, starting in the status row's column, with
segments joined by a dim " │ ". Each card's segments are short forms of its rows. The
working directory, model, thinking level, permission mode and context are
in the input box's status row ("The input box"), so the status line leaves
them out. Its segments are "git" dim and the branch in secondary; the cost
and "cache" dim with its share, then the time until it resets; "tools N" dim and
any down server in error; "±" dim, "N files" and the added and removed
totals; "◆" in secondary before the delegates; "⚙" in attention before
the jobs; and "Q" dim before the quota, with a limit nearly spent in error.
The Quota segment joins each short name and figure with a dim " · ". A
short name is the provider, with its credential label when it has more than
one. The window name follows only when that label has more than one
window. With no quota rows, there is no Quota segment.
With the rail hidden and sessions waiting, the first row opens with "N
waiting" in attention.
Shedding
The rail sheds before the panel. When the screen is too narrow for the rail's
floor, the conversation's minimum and the panel, the rail hides, and "N
waiting" joins the Session status card, or the status line while the panel is not shown; a
click on it shows the rail. A hidden rail leaves its grip at the screen's left
edge, and dragging the grip out shows the rail again, as does ⌥R. Shown while the
width has no room for it, the rail hides the panel, as ⌥P does; ⌥P brings the
panel back and the rail sheds again. A rail hidden
for width returns when the screen grows; one the person hid, by ⌥R, /rail or by
dragging it below its floor, saves tui.rail.shown as off and stays hidden,
across launches, until shown. Below the narrow layout, which
has already dropped the panel, the screen sheds the status line, then the
working line's detail. Below a floor of about 40 by 10
cells it shows one centred line, "Fiber needs 40×10 · now 32×8". The session
keeps running, nothing is lost, and the screen redraws on resize.
A dropped connection
A session that exits while on screen stays on screen until the connection is
lost, because its conversation is its log. Sending a prompt resumes it
through the hub, with no banner. On reconnect the terminal reopens the
attached session; it resumes idle and takes nothing until a prompt.
When the hub cannot be reached, a banner replaces the working line:
"Connection lost · reconnecting (attempt 2)…". The terminal retries with backoff while the conversation and the
draft stay. After reconnecting, the terminal sends sessions once and drops
every live row its answer does not list, unless a feed line for that row
arrived after sessions was sent.
The conversation
Turns
One card per turn. Prompts render as Markdown like replies, except
headings retain their leading # marker. This applies to prompts in the
bubble and to labelled start/session messages in the card. Only the
person's prompt floats above its card, after a blank row, as a bubble on the right in the prompt tint, at most 72%
of the width: the text padded one column on each side, a ▐ stripe in
accent at its right edge, and "you 14:12" dim and right-aligned under it.
A blank row separates the bubble from the card. The card is a turn slab
across the conversation's width, and its rows sit one column inside the
tint on each side. Blocks inside the card are separated by a blank row.
A steering message sits inside the card where it landed, as a labelled
rule over bold text: "steer" bold in attention, " · 14:15 " dim, then a
─ rule in rule to the card's edge. A dim ▣ line closes the card
with the outcome, duration, call count and the turn's usage, its delegates'
spend during the turn included: "▣ completed · 38s · 12 calls · 18.2k tokens
· $0.41 · $1.10 on subscription". A figure that is zero is left out, and a
model with no price shows tokens only (docs/model-routing.md, "Cost").
Non-driver messages stay in the card. A non-driver input message sits
inside the card where it landed as a labelled rule. Start-input messages
open the card, before any entry, in the input's order. A Fiber message has a
muted Fiber label, a dim · <time>, and dim text without one leading
Fiber: ; a session message has its current name or id as a secondary
label, a dim · <time> and full-colour text; an extension message has its
name as a secondary label, a dim · <time> and full-colour text. Images
draw below text. A blank message draws only its labelled rule. A whole-turn
copy includes each message's label and text in draw order; the labelled
rule is decoration and is not copied.
Replies lead, tool groups sit back. Nothing inside the card is indented
past its one-column padding: replies, summary lines, steering messages and
answers all start at the same column. A tool group has no band of its own, and its summary line is dim
throughout, the dot and the +/− counts included. Replies carry the full text
colour.
A streaming reply renders in place, formatted as it arrives. The
conversation follows new output and pauses when the person scrolls up. The
mouse wheel over the conversation scrolls it 3 rows a step, a starting
point, not a measurement; PageUp and PageDown page it ("Keys"). The
conversation's last column is its scroll bar and never holds text:
while the conversation has more rows than it shows, a thumb of ┃ in
scroll, with no track, shows where the rows on screen sit among all of
them. Either pauses following when it scrolls up. When new output arrives
while scrolled up, a pill centred on the conversation's bottom row reads
" ↓ New messages below · End " in attention on the rule tint, its ends
rounded by ▐ and ▌ in rule, and jumps to the end on a click or End. It
gives no count. Nothing is added to the input box.
Tool groups and the ledger
A group is everything between two pieces of assistant text, thinking
included. A labelled rule inside the card also ends the group: a steering
message, the "you answered" rule, or a non-driver message. These land only
at a step boundary, so every call before the rule is in the group above it,
and the calls after it start a new group below it. The asking call and its
count stay in the group above its answers. Collapsed, it is one line: what was done by kind ("Read 34 files,
searched 84 patterns, edited 24 files +175 −83, ran 9 commands"), how many
times the model thought, and how long it took. While it runs, the line shows
the calls in flight. A call the model is still emitting shows its raw
argument text from tool_call_arguments_delta, because arguments are parsed
only once the call finishes streaming (docs/events.md). The counts of changed lines come from
tool_call_completed's changes.
Clicking the line, or Ctrl+O, opens the ledger: one row per call, split
by step, with each step's number in the gutter and its thinking line first.
A step is opened by step_started (docs/events.md, "Session and turn").
Clicking a row opens that call inline under its row, at most 20
lines; Enter on a focused row does the same. Enter again on the opened
call, or a click on its "… N more lines (Enter to view)", opens the whole
call in a swapped view ("Swapped views").
An outer call with inner calls is one ledger row. When an extension
runs a tool inside its own call, each inner call nests under the outer
(docs/events.md, "ran_by"). The ledger shows one row for the outer,
then one row per inner call, each two columns further in per level, with
the same glyph, kind, target and result it would draw on its own. Calls
nest at any depth: an inner call with calls of its own nests those under
it the same way. An inner call whose outer names no call of the turn
draws top-level, in push order.
The summary counts inner calls by kind, at every depth. An outer
call with inner calls never counts as a kind of its own: with codemode
the summary reads what the inner calls did ("Read 1 file, edited 1
file +3 −1, ran 1 command"), never "called 1 tool" for the script
itself. Edits inner calls make get the same file-change highlight and
+N −N totals.
Opening an outer shows its arguments first, then its inner rows.
For codemode the arguments are the script in its source argument,
drawn as dim text, at most 20 lines; then one indented row per inner
call. Each inner row opens inline under its row and in the swapped
view, as any call does.
While an opened call's row, or an open ledger's group line, is above the
conversation's top row and any of its content is on screen, that row stays
pinned to the conversation's top row. Scrolling into the opened output
keeps the row over the covered content row, drawn as the row it stands for,
on the card's tint, with hover highlighting it like any click target. When a
call is opened inside an open ledger, only the innermost one pins: the
call's row. Clicking the pinned row closes what it opened, and the
conversation scrolls so the closed row sits at the top. Ctrl+O keeps its
current meaning. Whenever a find, a search-results jump, keyboard focus or
a reveal scrolls a row into view while a row is pinned, the visible top is
the row under the pin, with the pin staying.
A call that changed a file is highlighted in the ledger, with the file's
name and its lines added and removed, so edits stand out from reads and
commands. Its counts are in added and removed, where every other result
is dim.
Failed calls get no special treatment. They are ordinary rows with their
status. Nothing is hoisted above the fold.
The summary line is one row, whatever runs: "● " dim, then the kinds in a
fixed order, each clause dim, " N " or, where the table below
says so, " once" and " N times": read files, searched patterns,
listed directories, edited files, wrote files, ran commands, started
delegates, checked jobs, asked questions, fetched pages, searched the web,
loaded skills, looked up tools, messaged delegates, messaged sessions,
looked at sessions, saved reviewer notes, called tools. The first word is
capitalised. Read, edited and written files count distinct paths, and asked
questions count questions, not calls. delegate_models counts as a delegate, and
compact, name_session, session_list and session_search count as
one kind, looked at sessions, and reviewer_notes_save is its own, saved
reviewer notes. An edit's totals follow it, "+N" in
added and "−N" in removed, both dim. Then ", thought N times" ("thought
once"); while calls run, " · " and their targets, dim; while the model
thinks, " · Thinking: " dim and italic. Right-aligned, dim, the
group's duration and ▸ while closed or ▾ while open. What does not fit is
cut with "…", so the duration and the toggle stay put.
● Read 34 files, searched 84 patterns, edited 24 files +175 −83, thought 3 times 4m 12s ▸
A ledger row is the step's number right-aligned in a five-column dim gutter
on the step's first row. A step number longer than five digits widens the
gutter, and the row is cut to its width. Then a glyph: ○ in attention
while the call runs or waits, ✓ in success once it completes, ⊘ dim when
cancelled, ✗ dim otherwise. Then the call's kind in info, padded to nine
columns, its target cut with "…", and its result: "N lines" for a read, "N
matches" for a search, "N paths" for a listing, "+N −N" for an edit, "exit N
· N lines" for a command, otherwise the first line of its output, all dim
but the edit's counts. A call whose arguments a before_tool hook rewrote
draws the arguments that ran: tool_call_started's arguments, or
permission_resolved's on a reviewed call's decision that has no request
(docs/events.md, "changed_by"). Its result is then followed by " · via
", dim, the changed_by extensions joined by ", "; a rewrite with no
changed_by draws no mark. A running call reads "running" in attention, and an
ask waiting on the person "waiting on you"; "cancelled", "denied" and a
failure's ": " are dim. A thinking row is "○ Thinking:
" or "+ Thought: · 22s", dim and italic.
Every built-in tool has a kind word and a summary phrase, so the word
other and "called N tools" are for MCP and extension tools and for an
ask_user call with no question list; an extension that replaces a
built-in name keeps that name's kind. A shell
call whose command starts with grep or rg is a search, and one that
starts with find, ls or fd a listing; the shell row is for any
other command. Each word fits the nine-column pad. A test reads this table and
fails when it differs from the code.
Tool
Kind word
Summary, many
Summary, one
ask_user
ask
asked N questions
asked 1 question
delegate_fork
delegate
started N delegates
started 1 delegate
delegate_message
message
messaged delegates N times
messaged delegates once
delegate_models
delegate
started N delegates
started 1 delegate
delegate_spawn
delegate
started N delegates
started 1 delegate
edit
edit
edited N files
edited 1 file
compact
session
looked at sessions N times
looked at sessions once
jobs
jobs
checked N jobs
checked 1 job
name_session
session
looked at sessions N times
looked at sessions once
read
read
read N files
read 1 file
reviewer_notes_save
notes
saved reviewer notes N times
saved reviewer notes once
session_list
session
looked at sessions N times
looked at sessions once
session_message
message
messaged sessions N times
messaged sessions once
session_search
session
looked at sessions N times
looked at sessions once
shell
shell
ran N commands
ran 1 command
skill
skill
loaded N skills
loaded 1 skill
tool_search
tools
looked up tools N times
looked up tools once
web_fetch
fetch
fetched N pages
fetched 1 page
web_search
web
searched the web N times
searched the web once
write
write
wrote N files
wrote 1 file
An opened call is drawn under its row, indented eight columns, at most 20
lines, then "… N more lines (Enter to view)" dim when there is more. A
failed call shows ": " first. An opened thought shows its
text there. What an opened call shows depends on its kind, read from the
call's details (docs/tools.md, "What a result carries"); a call whose
details the terminal does not recognise shows its content:
An edit shows its diff in the diff format below.
A read shows the text read, with the line-number gutter starting at the
first line read, from details. A write, a call whose arguments hold a
string content, shows that text, numbered from 1.
A search shows its matches grouped under each file's path, the path
bold, line numbers in the gutter and the matched text on the match
tint, from the built-in grep's details. A search call without them,
such as rg or command grep, opens as a shell call.
A shell call shows the full command, "$ " and the command wrapped,
then the output, then one closing line: "exit N", in removed when N is
not 0 and dim when it is, or "killed by ".
A message call (delegate_message, session_message) shows "to
" dim, then the message text rendered as a reply's Markdown is, at the
width of the view it is drawn in, then the result. They come from the
call's arguments (id and message, or id and text), not its
details, so a running or failed call shows them too; a failed call's
": " still comes first. A part that is absent, not text or
empty draws no row. The ledger row's target is the recipient's description, for a delegate, or its
name, for a session, else the id. The row shows the name held when it was
folded, and a page loaded again is folded again. When the result has
an artifact, the swapped view draws these rows before the paged output.
An MCP call, an extension's tool, or any tool whose details the
terminal does not recognise shows content as plain text. Text that is
JSON is indented two columns per level.
The diff format is shared by an opened edit and the changed-files view. Each
line has a dim line-number gutter: the old file's number on a - line, the
new file's on the others. @@ lines are dim, - lines in removed and +
lines in added. When one removed line pairs with one added line, the words
that differ are in reverse video. There is no syntax highlighting.
1 ✓ edit crates/tui/src/view.rs +6 −2
@@ -12,5 +12,6 @@ fn paint(
12 let spans = fit(&r.spans, w as usize);
13 - buf.set_line(x, y, &line, w);
13 + buf.set_line(x, y, &Line::from(spans), w);
14 if let Some(bg) = r.bg {
15 + let line = Line::from(spans);
A group opens by a click, by Ctrl+O, when a search match falls inside its
ledger, and when one of its calls asks the person.
Thinking
Thinking belongs to the group it starts, since a group runs from one reply, or
labelled rule, to the next. The summary line counts it ("thought once") and, while it streams,
ends with "Thinking: ". Thinking with no tool call before the
next reply is one dim italic line, "+ Thought: · 22s", or
"Thinking: " while it streams, and clicking it shows the
text. A heading is the first line of the thinking text that is a
Markdown heading (#…) or wholly bold (**…**), with the markers stripped,
or the first non-empty line when there is none, cut to fit the line.
"Thinking:" shows the latest heading in the step so far, and "+ Thought:" the
first.
Steering
Enter during a turn sends steer. There is no follow-up queue: a prompt that
arrives mid-turn is still rejected busy (docs/invocation.md). A draft left
in the input box during a turn is untouched until sent.
Queued steering messages sit above the input box in the steering card, one
entry each, from the steering_queue event, so every attached client sees and edits the same
queue. ⌥↑ and ⌥↓ select a row and load it into the input box, Enter sends
steer_drop then steer, and ⌥X sends steer_drop. Each also has a mouse target.
The steering card sits under the working line and is drawn as a panel card
("The panel"): a surface slab edged ▄ and ▀ in surface, with two columns
of padding on the left and one on the right, and a stripe in attention down
its left edge. Its title row is "Steering" bold in attention, with "N queued ·
joins at the next step" dim, right-aligned. Each message
follows on its own entry: "↳ " in attention, the text in the text colour,
and a dim "✕" right-aligned. A message too long for the card wraps, its
continuation lines starting under the text rather than under the ↳. A
selected message reads "▸ " in attention and its text bold. The last row is the key hint, with each key bold and the
rest dim: "⌥↑ edit · ⌥↓ next · ⌥X drop · click a row to edit, ✕ to drop". A click
on a row selects it and a click on its ✕ drops it. While a message is being
edited, the input box's stripe is attention and the box ends, right-aligned
and dim, "editing a queued message · Enter amends · ⌥X drops · Esc stops".
Interrupts
Esc interrupts the turn when nothing is open ("Keys"). interrupt_turn, ⌥I,
interrupts the turn of the conversation on screen, whatever is open over it,
except the /keys screen: in a delegate's view, the delegate's turn, and
elsewhere the attached session's, leaving the overlay open. In a delegate's view a click on the
working line or on "⏸ interrupt" does the same, and Esc keeps closing the view.
The interrupt shows only
on the ▣ line that closes the card; there is no separate "Interrupted" line. A
call it stopped reads cancelled in its ledger row. With steering messages queued, they start
the next turn at once (docs/architecture.md, "Cancellation"), so Esc means
"stop, and read these". ⌥X drops them first for a plain stop.
Compaction
A compaction breaks the turn's card (docs/compaction.md). The card ends where the
compaction ran, and a tinted band carries:
the trigger: "automatic at 400k", "you asked with /compact", "the request
did not fit" or "the model compacted"
the context size before and after ("402k → 32k"); the size after comes from
the first request after the compaction that reports its input tokens, so it
reads "…" until that returns
the time
"▸ note" expands the note inside the band. While the note is being written the
band says so, with a spinner.
The band is one row on the compaction tint with ▄ and ▀ edges, across the
conversation's width: " ⇄ " and "compaction" bold, both in secondary, then the
trigger after " · ", dim; right-aligned, the sizes bold ("402k → 32k") and
" · 14:20" dim. While the note is written the sizes read "writing the note…"
dim; a failed or cancelled compaction reads " · the context is
unchanged" in attention.
A second card continues the turn, and its ▣ line
closes it. A failed or cancelled compaction says the context is unchanged. The
Session status card's context bar drops to the new size.
The nudge is one dim line where it happened: "◔ Context at 268k, two thirds of
the way to the 400k compaction. The model was told a compaction keeps the work
going."
Errors and retries
The terminal shows Fiber's message as it is and never rewrites it
(docs/errors.md).
While a retry is pending, the working line says so ("The working line").
Once a retry gets through, only a count stays, on the group's summary line
("1 failed model call"). The ledger has the detail.
A turn that fails ends with a ✗ line holding the message and the code, with
the provider's own words dim under it ("anthropic said HTTP 529:
“Overloaded”"), then ▣ failed.
A turn that fails with authentication_failed offers "log in" as a click
target on its error line ("Keys", /login).
mcp_server_failed is a ⚠ line in the conversation with its
error.message: "⚠ " in attention, the message dim, wrapped under
itself. A server that comes back writes mcp_server_ready, which
clears the Session status card's mark in every client.
Notices
Notices are rows at the bottom of the conversation, above the working line,
one row each until dismissed with ✕, oldest first: " ⚠ " and the code in
attention, " · " and the message dim, cut with "…", and a dim "✕"
right-aligned. Clicking a notice shows the whole text in an overlay.
One pass stacks one notice per code: a pass that finds the same failure
many times stacks one grouped row, whose message names the count and the
first item and lists every item. In one terminal run, a notice whose code
and text match one already shown does not show again.
At most 3 show, then "+N more", which lists them.
The "N approvals waiting" row (see "An approval") sits above the notices, and on a screen too short for both it drops first.
A notice that arrives during a drag waits for the release.
Not built yet: see #1506.
An accepted /import answer opens one import report overlay ("Look",
"Overlays") and adds no notices. The report is titled "Imported from
Claude Code" or "Imported from Codex", or "Imported" for a bare /import
covering both sources. It has two sections, "Copied · N" grouped by kind
(MCP servers, skills, commands, instructions) and "Left behind · N" in the
hub's order with each reason dim, and its foot reads "Imported items apply
on the next /reload · Esc closes" (docs/configuration.md, "Importing").
A failed import is one notice, as any failed command is.
When the hub sends stream_closed for the open session (it cannot read
the session's log to serve this terminal), the conversation keeps every line
it received and one notice shows: code stream_closed, "this session's log
can't be read past here; reopen the session to try again". A session that is
not open gets no notice. The terminal does not subscribe again on its own:
the fold would reach the same line. The composer is unchanged, so a send is
rejected not_subscribed and the draft comes back with that notice.
Reopening the session subscribes again through the normal open path.
When the hub runs another Fiber version or commit than this terminal, one notice says so on each connection: code hub_version, "The hub runs Fiber (this terminal: ). fiber stop restarts it on the next launch." The same text shows for a remote (listed) hub. (docs/invocation.md, "What the hub speaks").
A notice is an event or a condition. An event reports a failure once and
then fades: it clears 10 seconds after it shows, or when dismissed with
✕. A condition reports a state the terminal re-evaluates on its own
loop, and it stays until its cause ends: reaching its end clears it,
✕ only hides a row whose cause still holds. The loop sweeps notices
before each draw and before arming its wake, so a faded row never draws
and an expiry wakes the loop even with no input.
Code
Class
Clears when
cache_rebuild
event
Fades 10 s after it shows.
closing
event
Fades 10 s after it shows.
command_conflict
event
Fades 10 s after it shows.
config_invalid
event
Fades 10 s after it shows.
config_key_ignored
event
Fades 10 s after it shows.
connection_failed
condition
The connection cause clears when the hub reconnects; the search-incomplete cause clears when the find bar closes or a rescan completes. A reconnect alone never clears the search text.
credential_failed
event
Fades 10 s after it shows.
credential_missing
event
Fades 10 s after it shows.
extension_failed
event
Fades 10 s after it shows.
extension_incompatible
event
Fades 10 s after it shows.
extension_shadowed
event
Fades 10 s after it shows.
history_loading
condition
History lands for the pending turn.
hook_failed
event
Fades 10 s after it shows.
hub_version
event
Fades 10 s after it shows.
indeterminate
event
Fades 10 s after it shows.
instructions_large
event
Fades 10 s after it shows.
invalid_arguments
event
Fades 10 s after it shows.
io_failed
event
Fades 10 s after it shows.
login_url
condition
No automatic clear: finish the login in X, then dismiss with ✕.
malformed
event
Fades 10 s after it shows.
model_invalid
event
Fades 10 s after it shows.
model_omitted
event
Fades 10 s after it shows.
model_unconfigured
event
Fades 10 s after it shows.
models_loading
condition
The model list arrives.
no_jobs_running
event
Fades 10 s after it shows.
no_model
event
Fades 10 s after it shows.
repository_code_skipped
event
Fades 10 s after it shows.
reviewer_selection_failed
event
Fades 10 s after it shows.
reviewer_setup
event
Fades 10 s after it shows.
session_held
event
Fades 10 s after it shows.
session_not_found
event
Fades 10 s after it shows.
skill_invalid
event
Fades 10 s after it shows.
skill_shadowed
event
Fades 10 s after it shows.
skills_large
event
Fades 10 s after it shows.
stale_request
event
Fades 10 s after it shows.
stream_closed
condition
The session reopens; opening another session drops other sessions' rows.
switch_pending
condition
The turn ends and the switch applies; rejecting a pending command voids its claim.
tool_definitions_large
event
Fades 10 s after it shows.
web_search_unavailable
event
Fades 10 s after it shows.
Codes no table lists — a refusal or driver code the hub names
dynamically — are events: they fade after one showing.
Notices are not logged, so they are this terminal's own memory. A client that
attaches later never sees them.
After a crash
The reopened session closes the cut-short turn's card with "▣ cut short: Fiber
stopped at 14:18", at the time of the last line written. A call that started
and never completed reads "? may have run; not run again" in its ledger row. A
↺ resumed band follows. The jobs the new process marked orphaned, which no keeper
accounted for, are one line naming them all; clicking it shows each job's
message. A job the keeper finished while the session was gone gets its usual
completion row.
Naming the session
/name <text> names the session with the name driver command. The name is
written to the log as session_named, so every client sees it. The session
list, the rail card and the terminal title show it in place of the first prompt.
The model keeps the name current with name_session until a person's name
pins it (docs/tools.md, "Naming the session"). A name is drawn with each control character replaced by a space, in the session list, the header, the rail and the terminal title.
Rewind
/rewind swaps a view into the conversation area (docs/events.md,
"Rewind"). /fork is a rewind to the latest point: it sends rewind with
at_end, opens no view and offers no summary.
Each turn is one row, "before: ", or "before: rewind summary" for
the turn a rewind's summary ran in. The chosen turn opens into every
step boundary: after the person's message and after each step, with the
step's summary. The default is the start of the latest turn that is not a rewind's summary.
For the chosen point it shows the files Fiber's tools wrote since, the calls
that may have changed files, and that none of it is undone. It lists every
job that still runs, all of which stop.
An optional summary, then Rewind. The conversation is cut at the point, and a
⟲ line names the new session and says what was not restored and which jobs
stopped. The new session waits for a prompt.
session_held shows as the error in place of the Rewind button.
summary_failed shows the reason with three choices: retry, rewind without
a summary, or cancel.
Moving workspace
/cd <path> sends change_workspace (docs/invocation.md, "Driver
commands", change_workspace), and the screen switches to the new session.
The old session leaves as it does after a rewind: session_left has
how: exited. No move-specific text appears. With no path, the command notes
/cd needs a path. and sends nothing. When the session refuses the command, a notice
gives the refusal's code and message, and the screen stays on the session it
shows.
Approvals and questions
Approvals and questions waiting at the same time share one queue, "1 of N" in
the order they arrived, each labelled with the session asking.
An approval
An approval request is a panel at the bottom that replaces the input box
(docs/permissions.md).
The choices are: allow once; allow for this session; always allow in this
project; and deny, with optional feedback. Typing while the panel is open
goes to the feedback. The two remembering choices show the prefix the rule
allows, the one the request offers (docs/permissions.md, "What a rule
matches"). A request that offers no rule shows neither.
The panel says why it asked: the standing rule that asked, the reviewer's
reason when the reviewer escalated, or that the reviewer failed.
The panel's tint follows why it asked. A reviewer's escalation gets the
alert tint; a standing ask gets the normal approval tint. A call that
declares itself irreversible says "irreversible" in the panel's header, as
text, whatever asked. Nothing judges danger by reading the command
(docs/permissions.md).
The asking call's tool group expands so the full call can be read.
Esc puts the request aside. It stays pending behind a badge, and clicking the
badge reopens it. Denying is always explicit.
Esc steps through waiting requests one at a time. With a question form
behind an approval, a second Esc declines the form.
/approvals reopens the waiting queue at the first request. It is the key
path for reopening a request put aside and for moving to the next.
The mouse wheel over the panel's rows does nothing.
The panel is a slab with ▄ and ▀ edges, every row starting with a ▌ stripe
and a space: the approval tint and an attention stripe for a standing
ask, the alert tint and an error stripe for a reviewer's escalation.
▌ Approval 1 of 1 · main Esc puts it aside
▌ shell cargo mutants -p hub
▌ runs a command · asked by the project rule cargo
▌
▌ ▸ 1 Allow once
▌ 2 Deny type to add feedback
▌
▌ ↑↓ choose · Enter confirms · typing goes to the feedback · click a choice
A review that offers a rule shows the remembering choices:
▌ Approval 1 of 1 · main Esc puts it aside
▌ shell cargo mutants -p hub
▌ runs a command · the reviewer blocked the last calls: rm -rf
▌
▌ ▸ 1 Allow once
▌ 2 Allow for this session cargo mutants *
▌ 3 Always allow in this project cargo mutants *
▌ 4 Deny type to add feedback
▌
▌ ↑↓ choose · Enter confirms · typing goes to the feedback · click a choice
The first row is "Approval k of n" bold in attention, which moves to the
next request on a click, " · " and the asking session in attention,
" · irreversible" in error when the call declares itself so, and "Esc
puts it aside" dim, right-aligned.
Then the tool's name bold in info and its main argument bold, wrapped.
When a before_tool hook rewrote the call, the row ends with " · via
", dim, naming the extensions that took attribution; a rewrite no
extension took attribution for draws no mark. The summary is the arguments
that will run, not the ones the model sent.
A request raised again keeps what the person typed, and shows the
arguments of the latest raise.
Then one dim facts line: the call's declared effects joined by ", ",
" · " and the paths it names, and
" · " and why it asked: "asked by the rule ", "a standing
ask rule matches it", "it would leave readonly", "the reviewer failed",
"the reviewer blocked the last calls: " or "the reviewer has
blocked too many calls: ".
After a blank row, the choices, numbered: "▸ " in attention on the
focused one and two spaces on the others, the number dim, the label bold
when focused. The remembering choices end with the rule's prefix and " *"
in info. Deny ends with " type to add feedback" dim, or the feedback as
typed with a cursor. The numbers label the rows; a digit typed is
feedback, like any other key.
After a blank row, the hint, dim.
A request put aside leaves a row above the working line, " ⚠ N approvals
waiting · click to reopen", bold in attention, the ⚠ not bold.
A question form
An ask_user question form is a panel at the bottom that replaces the input
box, as an approval does (docs/tools.md, "Asking the person").
One question shows at a time. Across the top is a tab per question header,
marked when answered, then a Submit tab that shows every answer and takes a
note on the whole form.
Each question shows its options with their descriptions, and a row to
answer in words. Enter on a single-choice option chooses it and moves on.
In a multi-choice question, Space toggles the option under the cursor and
Enter moves on to the next question, or to Submit after the last one. A
multi-choice question ends with a Next → row, Review → on the last
question, that does the same for the mouse.
← and → move between the tabs, except in a row that takes typed text (the
answer in words, or the note), where they move the cursor. Tab and Shift+Tab
move between the tabs from any row.
"Chat about this", and Esc, decline the form and end the turn, so the person
can answer in their own words. The terminal sends reply with declined,
then cancel: the call completes declined, and the cancel ends the turn.
The cancel follows only an interaction a tool call raised, one whose
interaction_requested carries action_ids. One raised outside a tool call,
such as an extension command's host.ask, is declined and leaves any running
turn alone.
Once answered, the answers sit in the turn's card as a "you answered" rule,
like a steering message, one row per question, with skipped and the note
shown. The call's ledger row reads "answered" or "declined", and the group
line counts "asked 4 questions".
The form is an approval slab with ▄ and ▀ edges, every row starting with a
▌ stripe in secondary and a space:
▌ Question from main · 3 questions, any can be skipped · 1 of 2 Esc: chat about this
▌
▌ ← ✔ Scope ☐ Tests ☐ Docs ✔ Submit →
▌
▌ Which crates should the change touch?
▌ choose any
▌
▌ ▸ 1 [x] hub the session host
▌ 2 [ ] tui the terminal
▌ 3 ✎ Type an answer, alone or with the options
▌ Next →
▌
▌ ←→ question · ↑↓ choose · Enter chooses and moves on · Space toggles · type to answer in words
The title row is "Question" bold in secondary, " from · N
questions, any can be skipped" in secondary, " · k of n" bold in
secondary when more requests wait, and "Esc: chat about this" dim,
right-aligned. A blank row follows.
The tab row: "← " dim, a tab per question, " ☐ " or, once
answered, " ✔ " in accent, the current tab reversed, then
" ✔ Submit " and " →" dim. A blank row follows.
The question bold, wrapped, with "choose any" dim under a multi-choice
question, then a blank row.
Each option: "▸ " in secondary on the cursor's row, its number dim, a
mark, "( )" or "(•)" for one choice and "[ ]" or "[x]" for any, in
secondary when chosen and dim otherwise, the label, bold when chosen and
underlined under the cursor, and its description dim. A digit chooses that
option, outside a row that takes text.
The row to answer in words, numbered after the options: "✎ " dim, then
"Type an answer, alone or with the options" dim ("Type an answer" with no
options), or the answer bold with a cursor. The dim text is a placeholder:
with the cursor on the row, the cursor sits on its first character, drawn
reversed, and the first key typed replaces it.
In a multi-choice question, "Next →", or "Review →" on the last question,
in secondary, bold under the cursor.
After a blank row, the hint, dim: "←→ question · ↑↓ choose · Enter chooses
and moves on · Space toggles · type to answer in words".
The Submit tab is "Review" bold, a blank row, one row per question, its
header padded to 13 columns in accent and the answer bold or "skipped" dim,
then "▸ " in secondary, "note" in accent and "Add a note on the whole
form" dim, or the note bold, with a cursor. After a blank row, " Submit "
reversed and " Chat about this " on the rule tint, then " declines and
ends the turn, so you can answer in your own words" dim; after a blank row,
the hint, "←→ question · Enter submits · type to add the note · Esc: chat
about this", dim.
In the turn's card the answers are a rule like a steering message: "you
answered" bold in accent, " · 14:16 " dim and a ─ rule in rule. Under it,
each question's header padded to 13 columns in accent, then the answer bold
or "skipped" dim, and "note" with the note in quotes, bold. A declined form
reads "declined: the turn ended so you could answer in your own words" dim.
The other interactions, confirm, select, multi_select and text_input, raised by an extension's host.ask and by MCP elicitation, are drawn as one-question forms: the same panel with no tab row, the question, then its rows, ending with "Chat about this". confirm shows two options, yes and no, and Enter on one replies confirmed. select shows the options, and Enter on one replies labels with that label. multi_select shows the options: Space toggles one, and Enter replies labels, possibly empty. text_input shows only the row to answer in words, and Enter replies text as typed. The last two end with a Submit row that does what Enter does, for the mouse. Esc, and "Chat about this", decline as on a form.
Reading and copying
Selection and copy
Dragging selects text on any surface that shows it, and copies on release,
as the conversation does today. That covers the input box, notices, panel
cards, overlays (pickers, the login overlay, /settings), the approval
panel, question forms and swapped views. The press claims the surface it
starts on: a drag selects within that surface and does not spill into a
neighbour, even when the pointer leaves the window. "Copied" shows in
info in the conversation's top-right corner, below the search box when
it is open. The selection is on the selection tint, painted over every
surface's own rects. The terminal owns Cmd+C (Ghostty binds
super+c=copy_to_clipboard), which is why release copies.
A surface's renderer already draws its text as spans, the same spans that
make selection, copy and search work in the conversation. Every surface
uses that span shape. A span is either text or decoration. What a
selection copies is the text spans that fall inside it. Decoration never
goes into the copy: stripes, half-block edges, chips' brackets, key
hints, the focus gutter and mark, borders, the scroll bar, and the "…"
a cut adds. A selected paste token or image copies its visible label,
never its hidden payload or bytes. A row that wraps onto the next is
joined with no newline; a line break in the text is a newline. Trailing
spaces on each row are dropped. A cut element copies what is drawn,
without the "…". Its whole text is one click away, in the overlay.
The copy goes through OSC 52 and, on a local session, the system clipboard
command as well. tmux's default set-clipboard external drops OSC 52
silently, and over SSH only OSC 52 reaches the person's clipboard.
/copy copies the newest reply in the conversation on screen the same way,
and "Copied" shows: the text parts of the model's latest message that has
text, as the model wrote them, Markdown included, joined by a blank line.
With no reply yet, a notice says "No reply to copy yet." When the window
holds no reply newer than a page it has dropped ("History and paging"), the
newest reply may be on that page, so nothing is copied and a notice says "The
last reply is paged out; jump to the end, then /copy again." While an opening
pass folds a session's history ("History and paging"), the conversation on
screen stays as it was, so /copy waits and copies in the frame after the
pass ends. The next key, edit or click, a view opening or closing, leaving the
session, a session attaching and a lost connection each drop the wait, so it
never copies from a screen the person has moved on from. A job's view, and a
delegate's view with no transcript, hold no reply: there /copy says "No
reply to copy in this view."
Shift-drag stays the terminal's native selection. A selection's highlight
counts as open, so Esc clears it before it can interrupt the turn.
The input box keeps the selection as the editor's selection too. Typing
or a paste replaces it, and Backspace or Delete removes it. An unshifted
cursor key clears it: ← and Home leave the cursor at the selection's
start, and → and End at its end; ↑ and ↓ clear it and then move as usual.
A click in the box clears the selection and places the cursor. Shift with
the arrow keys stays out of this rule. Release still copies.
A press-and-release with no movement is still a click, so mouse targets
keep working. A drag that starts on a target selects instead of clicking:
once the pointer leaves the press's cell the click is disarmed and the
release clicks nothing. Rail and panel edge drags keep resizing and never
start a text selection.
A notice that would fade, or an overlay that would close by itself, waits
while a drag is in progress. On release the copy happens first, then the
waiting fade or close. A close the person asks for, such as Esc or a
click, is never part of a drag, so this rule does not touch it.
Search
Search covers the whole session log, matching rendered text, never raw JSON
lines. It matches the unwrapped text and marks a match across the rows it
wraps onto.
The search bar floats over the conversation's top-right corner, as an
editor's find box does, and the input box keeps its draft. It is 40 columns
wide, a surface slab with ▄ and ▀ edges: " ⌕ " in attention, the query
bold, the cursor ("The input box"), and right-aligned "3 of 41", or "no matches" or "type to
search" dim. Every match is marked on the match tint, the current one on
match_current. A match inside a collapsed section expands it when it
becomes the current match.
Matching is plain text: it folds case per character, matches literally, and
keeps at most 10,000 matches ("10000+"). No model ranks the matches or
interprets the query. Enter or ↓ moves to the next match, Shift+Enter or ↑
to the previous; both wrap.
Ctrl+F a second time, or a click on the "3 of 41" count, opens the search
results as a swapped view ("Swapped views"): every match, one row each, with
the lines around it. Each match's first row ends with turn N, dim and
right-aligned, where N is the number of the turn the match is in, counted
from 1 as the usage view counts turns; a match outside any turn, or a row
too narrow to hold it after the path, has no label, and the path is never
cut for it. A match's path is the file of the tool call it sits in; a match
with no such file, in a prompt, a reply or another call, has no path, and
its row is turn N alone. Enter, or a click on a row, jumps to that match
in the conversation and closes the view.
Search is Ctrl+F, and Cmd+F where the terminal forwards it. Ghostty binds
super+f=start_search by default; the line that frees it is:
keybind = super+f=unbind
How search reads a large session is "History and paging".
Links
Mouse capture turns off the terminal's own link detection, so links are
handled on click: an escape sequence in a cell breaks the width measure.
Markdown links (tables included) and bare http:///https:// URLs open
on click; schemes are http, https and mailto. A click runs open or
xdg-open on the terminal's machine; over SSH or with no opener the click
copies the URL and shows "Copied". A link is in the accent colour,
underlined. A focused link sits on the surface_raised tint, with "Enter opens
· y copies" dim under it when the window has a row under it, and opens with Enter and copies with y. A hovered
link takes the hover tint.
A focused link keeps the surface_raised tint under hover, whether the pointer is on the link itself or on a wider target that covers its cells.
A copy, link or image command still running after 10 seconds is stopped;
what it started keeps running. Large images go to the terminal in chunks (Images).
Keys
Rules
Detection never blocks the first frame. The terminal sends kitty's
keyboard flags query, the XTVERSION query, and a primary device attributes
query, then the kitty graphics probe, and draws at once. Bindings that need the kitty protocol switch on when the
reply arrives. crossterm parses both replies but hands them only to a call
that blocks for up to 2 seconds, so Fiber reads terminal input itself
(fiber-zig#16).
Input is read in the order it arrives. Each key, paste or mouse report
becomes one event, in the order its bytes came: a bound control character
then a letter is the binding's action, then the letter, and nothing else.
A byte that starts no key is dropped and reading goes on from the next
byte. A control character with no binding is dropped whole, a two-byte C1
control included. An escape sequence cut by a byte that cannot continue it
drops its ESC [, and reading goes on from that byte. Invalid UTF-8 drops
one byte and keeps the rest.
Every action has a key. Every action also has a mouse target or a slash
command, except editing the draft in the input box and search, and choosing
in the model picker or the credential picker for this session only.
A mouse target is drawn only where one fits naturally, never as a
button added only so the mouse has a way in. A key that needs the kitty
keyboard protocol also has one that does not, so every action keeps a key
on any terminal.
Esc closes whatever is on top, except the workspace picker while no
workspace is chosen ("Home"). On home, Esc on a focused row goes back to the session the person came from ("Home"). It returns focus to the input box from
the conversation, and interrupts the turn only when nothing is open and the
input box has focus. In a question form, Esc means "Chat about this".
PageUp and PageDown move one screen wherever something scrolls: the
conversation, every view, every picker and every list. A screen is the
scrolling region's own visible rows, not the terminal's height.
The reviewer setup is the reviewer-setup skill (docs/permissions.md,
"Setting up the notes"): typing /reviewer-setup loads it, and the
session's agent drafts the notes with you. The first time in a session the
reviewer blocks a call while both layers of the notes are empty, a notice
names the skill.
Slash commands. Typing / opens one completion panel above the input
box. Commands, skills, prompt templates and MCP prompts share one list,
filtered as the person types. Each row is a name, a one-line description, a
skill's argument-hint when it has one, and a tag: command, skill,
template, the extension's name, or the MCP server's name. Tab completes and
Enter runs. The panel is an overlay above the input box ("Look",
"Overlays") with no title and at most eight rows. A row is the name in
accent in one column as wide as the longest name shown, the letters
that match the query bold; the description dim, cut with … so the tag
always fits; the argument-hint in attention; and the tag dim at the
right end. The first match is focused. When the list does not fit, a last
dim row says where the rows shown sit: "1–8 of 43 · ↓ 35 more", with "↑ 3
above · " in front once it has scrolled. With nothing matching, the panel
holds one dim row, "no matches". A
skill the model has loaded shows in the transcript as a skill, not as a file
read.
File search. Typing @ opens a file search panel, and choosing a file
inserts its path as text. It is drawn as the / panel is, one path per
row in accent, cut from the left when long so the file name stays, and
"no files match" dim when nothing does. The model reads the file itself if it needs it.
@foo searches the files git tracks in the workspace's repository, so a huge
repository costs one listing, never a walk of the tree. @ followed by /,
~/ or ../ searches the machine instead: the text up to its last / is the
base directory (~/ starts at home, ../ at the workspace) and the rest is
the query. The base's own matching entries come first, directories first, then
matching entries deeper under it from one walk that honours .gitignore, skips
.git, and stops at 50 rows or 100,000 examined entries (entries the walker
skips are not counted). Rows read as typed, a directory ending in /: choosing
one enters it and keeps the panel open on the new base, choosing a file inserts
its path and closes the panel, and a base that cannot be read says why.
Each keystroke cancels the last search, in either mode.
A remote terminal searches the hub's machine in both modes: ~/ is the
hub's home and ../ starts at the workspace there. The path listing stays
on the hub; only the ranked rows reach the terminal.
Moving through the conversation
The input box holds the keyboard until the person moves focus out of it.
Shift+Tab moves focus to the newest item in the conversation.
↑ and ↓, or k and j, move focus through turns, tool groups and their
ledger rows, scrolling the conversation as needed.
Enter opens the focused item, as a click does: a group's ledger, a call
inline under its row, a delegate's view. Enter on an opened call opens
its swapped view.
y copies the focused item's text. Ctrl+G opens it in the editor ("The
editor").
Tab moves focus to the panel, then the rail, then back to the
conversation.
Esc returns focus to the input box, keeping the draft, except on home,
where Esc on a focused row goes back to the session the person came
from ("Home").
The focus order is not defined screen by screen. It is every click target on
screen, the same targets hover highlights, and each turn, from top to bottom and left to
right. Every mouse target, an extension widget's included, is therefore a
focus stop with no extra work, and nothing the mouse can reach is out of the
keyboard's reach.
The editor
Every Ctrl+G, and "Open in editor", runs one editor command: tui.editor
when set, else $VISUAL when set and not empty, else $EDITOR. The
command runs on the person's terminal, so on a remote terminal it is the
client's. With none of the three set, Ctrl+G opens nothing and shows the
notice "No editor set. Choose one in /settings: Editor."; a click on it
opens /settings with the Editor row focused.
The input box
The input box is a surface slab with ▄ and ▀ edges across the
conversation's width: a ▌ stripe in accent, a space, "› " in info, the
draft, and the cursor. While search is open, typing goes to the
search box and the draft shows without a cursor.
The cursor, here and wherever Fiber draws one, is the cell under it drawn
reversed: its character in the slab's colour on the text colour. Past the
last character it is a block in the text colour. The character under it
stays readable in light and dark mode.
Under the draft and inside the slab, the box ends with a rule and its
status row, in every layout, and the status line after them while the panel
is not shown ("The narrow layout"). The rule is ─ in rule from the
stripe's next column to one column short of the slab's right edge. The
status row has two sides. On the left: the working directory, then the
permission mode in attention. Right-aligned, ending one column short of
the slab's edge: the model in accent and the thinking level in
attention, then "ctx" dim, an 8-cell context bar, the size and the share
of the window dim ("ctx ▆▆▆▆▆▆▆▆ 268k · 26%"). Segments on each side are
joined by a dim " │ ", as in the status line ("The narrow layout"), and
the two sides keep at least two columns between them. The row says nothing
about compaction: the compaction point is in the Session status card and the
context breakdown. When the row is too wide, the working directory is cut
from the left to keep its last part ("…/fiber"), then the left side is cut
at its right end; the right side is cut only when the slab is narrower than
it, at the slab's right edge. Clicking the model or the thinking level
opens the model picker, as Ctrl+L does; clicking the ctx segment opens the
context breakdown; clicking the working directory or the permission mode
opens the Session status card's view. An extension redraws the row
through the input_status slot ("Extension seams").
Enter sends. Shift+Enter inserts a line break, with Ctrl+J for terminals
without the kitty keyboard protocol. Pasted text keeps its line breaks. The box grows to about a third of
the screen, then scrolls.
Ctrl+U deletes from the start of the cursor's line to the cursor, the
line ending at a line break, not at the box's wrap; at a line's start it
deletes nothing.
↑ in an empty box recalls earlier prompts: from this session, then the
project's earlier sessions, newest first. Ctrl+R searches them. They come
from the project's prompt history (docs/state.md), read through the hub,
so a remote terminal recalls the same prompts. In a draft of several lines, ↑ moves
the cursor until it reaches the first line.
A paste over about 10 lines shows as one token, "[Pasted text #1 · 312
lines]", and the full text is sent. Clicking the token, or Ctrl+G with the
cursor on it, opens it in the editor.
Ctrl+V with an image shows "[Image #1]" and sends the image as an image
part in the prompt, which the session processes as it enters
(docs/invocation.md). The terminal reads the image with the system
clipboard command on the machine it runs on: osascript reading
«class PNGf» on macOS, and on Linux wl-paste --type image/png under
Wayland, else xclip -selection clipboard -t image/png -o. No terminal
protocol carries the read. Where that machine has no readable clipboard,
such as an SSH login, Ctrl+V shows a notice saying so and leaves the draft
as it is. An image over 50 megapixels (width × height, read from its PNG
header) or over 256 MiB is refused at the paste with a notice, and the
draft is left as it is.
!cmd runs a shell command and sends its output with the next prompt.
!!cmd runs it and shows the output only to the person (shell with
send false, docs/invocation.md). A ! or !! command has no
timeout: it runs until it exits, until cancel stops it, or until the
session shuts down. A draft is in shell mode when its
trimmed text starts with ! and it carries no image. Its first row then
opens with ! instead of › , and the box's top-edge row carries
shell for ! or shell · not sent for !!, right-aligned. A bare !
already marks the draft. Backspace past the ! clears the marker, and an
image draft shows none. The label is chrome and sheds first when the box
is cut short. The ! prompt stays. While a run is in flight and
the draft is outside shell mode, the box carries the run's label
instead, and the draft prompt stays plain. A shell draft keeps its own
marker and ! prompt. Each run shows as one transcript row:
! <command>, then sent with your next prompt for ! or only you see this for !!, then the output with
trailing whitespace dropped, then exit N (exit 0 included) or
signal S. A run with neither ending shows no ending. A command that
could not start shows ! <command> then <code>: <message> as it
arrived. A refused run puts that row on the attached screen beside the
notice. A session duplicate_command refusal draws neither a row nor a
notice. A run's output shows at most 20 lines, then a "N more lines"
row; clicking it, or Enter on it, opens the rest in place, and again
closes it.
While it runs, the row shows the output so far, then running, dim in
attention, where the ending will go; the ending replaces it. A !
row appears once the session records the command's start, which comes
before the command runs: at once, during a turn's tool calls too, and
as a model response ends when one is streaming. A !! row appears
when it is sent. A run whose session ended before its end was written
shows no ending.
Bindings
Action
Id
Key
Other paths
Send a prompt, or a steering message during a turn
send
Enter
Insert a line break
line_break
Shift+Enter
Ctrl+J
Close what is on top; interrupt the turn when nothing is open
close_or_interrupt
Esc
click the overlay's ✕ or outside it; click "Esc to interrupt"
Clear the draft, then quit
clear_then_quit
Ctrl+C, twice within about a second on an empty box
/quit, /exit
Go home
go_home
⌥0
/home
Start a new session
new_session
Ctrl+N
/new
Switch to the session of rail card N
rail_row_n
⌥1 to ⌥9
click the card
Delete the selected exited, or a live one with Delete session in the session list
delete_session
Delete, or Shift+Backspace, on the row
click a live row's ✕
Interrupt the turn on screen, whatever is open over it, except the /keys screen
interrupt_turn
⌥I
click a delegate's "⏸ interrupt" or its working line; click "Esc to interrupt"
Archive the selected exited session in the session list
archive_session
Backspace on the row
click an exited row's ✕; /archive
Recall an earlier prompt from the project of the session on screen
recall_prompt
↑ in an empty box
Move focus from an empty input box into the rail
focus_rail
← in an empty box
Search those prompts
search_prompts
Ctrl+R
Move by word
move_word
⌥← ⌥→, Ctrl+← Ctrl+→
Delete a word
delete_word
⌥Backspace, Ctrl+Backspace, Ctrl+W
Delete to the start of the line
delete_to_line_start
Ctrl+U
Start or end of the line
line_start_end
Ctrl+A Ctrl+E; ⌘← ⌘→ where the terminal passes them
Open the draft, or a pasted token, in the editor
open_in_editor
Ctrl+G
click the token
Paste an image
paste_image
Ctrl+V
Open or close the ledgers
toggle_ledgers
Ctrl+O
click a group's line
Move focus from the input box into the conversation
navigate
Shift+Tab
click an item
Move focus to the next or previous item
focus_next_prev
↓ ↑, j k
click an item
Move to the first row of the next or previous project in the session list
focus_project
Shift+↓ Shift+↑
click a row
Open the focused item
open_focused
Enter
click it
Copy the focused item
copy_focused
y
select it
Move focus to the panel, the rail, then the conversation
focus_area
Tab
click the area
Show or hide the panel
toggle_panel
⌥P
/panel
Show or hide the rail
toggle_rail
⌥R
/rail; drag its edge
Search
search
Ctrl+F; Cmd+F where forwarded
Open the search results
search_results
Ctrl+F with search open
click the match count
Next or previous match
search_next_prev
Enter or ↓, Shift+Enter or ↑, with search open
Jump to the end
jump_to_end
End
click "↓ New messages below"
Select a queued steering message
select_steering
⌥↑ ⌥↓
its mouse target
Amend it
amend_steering
Enter
its mouse target
Drop it
drop_steering
⌥X
its mouse target
Reopen a request put aside, or move to the next, the oldest first, switching to its session
next_request
⌥A
/approvals; click the badge or a waiting card
Open the model picker
model_picker
Ctrl+L
/model
Choose in the model picker for this session only
session_only
Ctrl+S
Show every model in the model picker, or only the scoped ones
show_all
Tab
click "[show all]"
Refresh every model list in the model picker
refresh_lists
Ctrl+R
click "⟳ refresh all"
Open the key map
key_map
F1
/? or /help
Every key bound to delete_session acts as Delete does. A rebound character key
stops on home's list and types on a focused rail. [] unbinds it. Every key
bound to archive_session acts as Backspace does on home's rows, and nowhere
else. Delete is the key that deletes without the kitty keyboard protocol,
where Shift+Backspace arrives as Backspace and archives.
The key map, /? or /help, is an overlay over the conversation listing every
binding by area with its other paths. Esc closes it. Ctrl+L opens the model picker,
so it does not redraw the screen as it does in some terminal programs.
The key map docks at the bottom, full width, in the overlay frame ("Look",
"Overlays"). Its title is "Key map" with a ✕, then two dim lines: "Every
binding by area, with its other paths." and the counts ("40 actions, 28 with
other paths"). After a blank row comes a row of tabs, "All" and then each
area, two columns apart: the chosen tab bold, drawn dark on white, the rest
dim; ← and → move between them. Under the tabs, the search line reads "Type
to search shortcuts" dim, then "› " dim and the typed query bold with the
cursor ("The input box"). Typing narrows the rows to bindings whose action, key or other paths
contain the query, ignoring case, across every area when the tab is All.
Each binding is one row over three columns that start at the same cell on
every row: the area dim, the action with any condition dim in parentheses
after it, and the keys dim, alternatives comma-separated and other paths
after " · ". Each column wraps inside its own width. The first row is
focused. When rows hide below, a dim ↓ takes the last shown row's gutter; a
screen too short for them scrolls, and its last line reads "↑ 4 more · ↓ 12
more" dim. The footer is "↑↓ move · ←→ tabs · Esc close".
Hints that name a key, on home, name the action's
bound key from this table, leaving the key out when the action is unbound.
Every action acts in some of six contexts, and the terminal is in exactly one
of them when a key arrives:
Overlay: something on top has the keyboard. That is the quit question, the
close-all and stop questions, the import report, the /delete question on
an attached session, the session-list delete question
on home, the workspace picker, the key map, an approval or question, an
offer, the hooks install offer, the Ctrl+R panel, or a notice's whole text;
or the / or @ completion panel while focus is not
in the conversation. An overlay's own keys, such as an approval's ↑ and ↓,
are not bindings.
Picker: the model picker or the credential picker is open. Only its own keys and the global actions
act.
Search: conversation search is open.
Conversation: focus is in the conversation.
Steering: a queued steering message is selected.
Input: the input box has the keyboard, home with nothing open included,
and so does a focused rail: typing there goes to the input box. On home,
↑, ↓, ← and → move between the session list, the entry bar and the chip
row ("Home"), and Esc on a focused row goes back to the session home came
from; on a focused rail ↑, ↓, Enter, → and Esc move and
switch ("The rail"); like an overlay's own keys, they are not bindings.
Delete on a focused rail card stops that session after asking ("Quit"); with
the input box focused it edits the draft.
A global action acts in all six. The rest act only where they are listed:
Input and Steering: line_break, search_prompts, move_word,
delete_word, delete_to_line_start, line_start_end, paste_image.
Every row in an overlay that takes text, as well: move_word,
delete_word, delete_to_line_start and line_start_end. That is an
approval's feedback, a question form's words row and its note, and
text_input.
Every action has a stable id, and keys."<id>" in the global configuration
binds it to a key or a list of keys (docs/configuration.md). The value
replaces all of the action's default keys, and [] leaves it unbound. An
entry equal to the defaults counts as unset.
A key name is any modifiers, then a key, joined by +, in any case:
ctrl+t, alt+up, shift+enter, super+left. The modifiers are ctrl (or
control), shift, alt (or opt, option, meta) and super (or cmd,
command). The key is one of enter (or return), esc (or escape),
tab, space, backspace, delete, insert, home, end, pageup,
pagedown, up, down, left, right and f1 to f12, or a single
character. An uppercase letter means Shift and that letter, and Shift on a
character that is not a letter is dropped. + alone, or after a modifier as in ctrl++,
is the plus key.
Seven actions have ordered variants: move_word (left, right),
line_start_end (start, end), focus_next_prev (next, prev),
focus_project (next, prev), search_next_prev (next, prev),
select_steering (up, down) and rail_row_n (1 to 9). Their list holds keys in groups of one key per variant,
in that order, so ["ctrl+b", "ctrl+f", "alt+b", "alt+f"] gives move_word
two keys each way. A list whose length is not a multiple of the number of
variants is invalid, and [] unbinds the action. A group identical to an
earlier one is dropped, and a key repeated in a one-variant action counts
once.
Two actions clash when they share a key, at any variant slot, and act in a
context in common. Actions whose contexts do not overlap may share a key, as
send, open_focused, amend_steering and search_next_prev share Enter.
At startup each clash gives one notice naming both actions. When an entry
the person set clashes with a default, that entry reverts to its defaults;
when two entries the person set clash, both revert. A revert can bring back a
default that clashes with another entry, so the check runs again until a pass
finds no clash.
An invalid entry gives one notice at startup, and the action keeps its
defaults. An entry is invalid when its id names no action, its value is not a
string or a list of strings, a string is not a key name, a variant action's
list has the wrong length, or one key sits in two variants of the same action.
No action can be bound to Ctrl+C, and clear_then_quit cannot be rebound,
because the second Ctrl+C always quits ("Input and focus"). Either entry gives
a notice and keeps the defaults.
/keys opens the rebinding screen: every action with its keys, id and
description, the unbound ones included. Each column wraps inside its own width, as in the key map, so every key stays readable. Every display line of a wrapped action takes a mouse target, and a click on any line selects the action; the focused action keeps the bar on every wrapped display line with › on the first, the /keys exception to the Swapped-views gutter-only rule. Selecting an action, pressing Enter
and then a key binds it, so only a key the terminal actually delivers can be
bound; an action with variants takes one key for each variant, in order. A key
already bound to another action shows inline, with a choice to swap or cancel.
A swap gives the other action, in that key's place, the key this action held
for the same variant; when there is none, or it would clash, the other action
loses that key's group instead. r resets an action to its defaults, through
the same swap or cancel when a default is now another action's. Delete, or
Backspace, unbinds it, saving []. The screen's own keys are fixed: ↑ ↓
PageUp PageDown move, and Esc cancels a capture or closes the screen, so Esc
is bound only by hand. Ctrl+C still clears, then quits, there. The screen saves
only the bindings that differ from the defaults, so a default changed in a
later release still applies.
Slash commands
Command
What it does
/home
Goes home, focused on the session on screen's row.
/new
Goes home with the cursor in the input box, to pick the workspace, worktree, model and thinking level for a new session. The session left keeps running.
/resume
Goes home, focused on the first exited row.
/model
Opens the model picker.
/thinking [<level>], /effort [<level>]
Sets the thinking level for the session's model, saving models."<model>".thinking; the default model is unchanged. Sent while a turn runs, the choice applies when the turn ends. The notice appears when the choice is sent; if the session rejects the choice, the rejection's notice replaces it. With no level, opens the model picker on the model's chips: Enter saves the level, Ctrl+S applies it to this session only.
/credential [<label>]
With no label, opens the credential picker ("Swapped views"): Enter switches to the chosen label and saves it as the provider's credential, Ctrl+S switches for this session only and saves nothing. With a label, switches to it and saves it. The label is saved under the provider the session accepted the switch on. The terminal first says the switch rebuilds the cache, with its size (docs/model-routing.md, "Which credential a session uses").
/scoped-models
Opens the model picker as a checklist over every installed model: each row starts marked from scoped_models. Typing filters the list as it does in the picker, Space included in the query. Enter or a click on the mark toggles the focused row's mark, and Ctrl+S, session_only's key, saves the marked list as scoped_models instead. Esc clears the query first and closes on the next press, saving nothing. Marks survive a query change. Each row carries its mark between the gutter and the id: [x] marked, [ ] not, bold on the focused row and dim when unmarked. The count row reads {m} of {n} marked unfiltered and {v} of {n} models · {m} marked filtered, with no show-all toggle and no refresh button. The row below each model is its thinking row, dim with nothing to choose. Ctrl+S saves and closes. The footer is "↑↓ move · Enter toggle · Ctrl+S save · Esc close", keys bold. Marking none saves [], which means every model; a saved entry that is not installed is kept.
/tools
Opens the tools view.
/hooks
Opens the hooks view.
/mcp
Opens the MCP servers view.
/context
Opens the context breakdown.
/usage, /cost
Opens the usage view.
/quota
Opens the quota view and fetches every label's quota.
/status
Opens the status view ("Swapped views").
/doctor
Opens the doctor report.
/diff
Opens the Changed files view ("Swapped views"), as the panel's card does.
/release-notes
Opens the running version's release notes, or says none are available.
/copy
Copies the newest reply ("Selection and copy").
/pwd, /cwd
Shows the session's workspace; on home, shows the notice No session on screen.
/add-dir <path>
Adds an existing folder to the session's boundary. Relative paths resolve from the workspace. A folder already inside the boundary is accepted without a change. The folder lasts for the session; /cd or a new session drops it. With no path, the terminal shows the command's usage.
/panel
Shows or hides the panel ("The panel").
/rail
Shows or hides the rail ("The rail").
/rules, /permissions
Opens the standing rules.
/settings, /config
Opens the configuration keys.
/theme [<name>]
Opens the theme picker; with a name, sets the theme at once and saves tui.theme.
/keys, /keybindings, /keymap
Opens the rebinding screen ("Bindings").
/skills
Opens the skills.
/rewind
Opens the rewind view.
/cd <path>
Moves the session to another workspace ("Moving workspace"). With no path, notes /cd needs a path. If the resolved path is the current workspace, refuses invalid_arguments, already in that folder.
/fork
Rewinds to the end of the conversation: sends rewind with at_end, and the terminal switches to the new session.
/compact [instructions]
Starts a compaction (docs/compaction.md, "A person").
/name <text>, /rename <text>
Names the session.
/login
Logs in ("Logging in").
/logout
Logs out ("Logging out").
/reload
Reloads configuration, MCP servers and extensions (docs/mcp.md, "Reload"), and re-enables a TUI extension a timeout switched off ("When an extension fails").
`/sandbox [on
off]`
/import
Copies another harness's configuration into Fiber home, once (docs/configuration.md, "Importing").
/clear
Starts a fresh session in place, closing the session on screen ("Clearing").
/close [all], /stop [all]
Stops the session on screen ("Quit"). /close all stops every live top-level session on this hub after one question ("Quit"): with no live session and no keeper it says "No sessions to close", and Enter closes exactly the sessions the question counted.
/archive
Stops the session and its cascade as /delete does, then archives that one session and goes home, asking nothing ("The session list").
/delete
Asks before stopping the session and its cascade, then deletes the exact confirmed set permanently; it never retries a refusal ("The session list").
/feedback <description>, /bug <description>
Writes a feedback report with the description, version, platform, doctor output and the diagnostics of the session on screen, and prints its path and the issue link. With no session on screen, the diagnostics are the hub's lines only. A session this machine holds no diagnostic lines for, such as one on a remote hub, still gets its id, the instruction to export its log privately and the hub's lines, with a notice that this machine has no diagnostic lines for it. The report also carries the shapes of the last 20 painted frames with the scroll state that produced each one — per cell its width class, style and whether it is blank, plus the frame geometry, never glyphs — captured on every frame with no flag set in advance, so a redraw bug arrives with its evidence; before the first frame it says no frames were captured. The report is the one fiber feedback writes (docs/invocation.md, "Commands and flags").
/quit, /exit
Quits ("Quit").
/approvals
Reopens the waiting approvals and questions.
/?, /help
Opens the key map.
/delegates, /agents
Opens the delegates view: every delegate of the session on screen, running and finished.
/jobs, /tasks, /ps
Opens the running jobs view: every running job of the session on screen, in the order they started. With no session on screen it shows the notice No session on screen.; with no jobs running it shows the notice No jobs running and opens nothing. Words after the command are ignored.
The / list shows built-in commands in this order.
/add-dir path/to/shared sends this driver command:
The range line's total counts every entry the query matches: the matching built-in rows plus the matching session commands.
A row's other names, such as /exit, are aliases: typing one runs the same command, and the / list shows them after the name on that command's row, never as rows of their own.
The rest of the list is the session's answer to the commands driver command
(docs/invocation.md, "What each command does") and the TUI extension commands
(docs/extensions.md, "Commands and screens"): its skills, prompt templates
and extension commands, each with the tag the answer gives. The terminal sends
commands when it attaches to a session and again after each reloaded,
each extensions_loaded, which an offer's approval writes with no reloaded
(docs/events.md, "extensions_loaded"), and each turn_started, and
fills the list from the answer to the latest one it sent; until that answer
arrives, the list holds the commands above only. A skill, prompt template or MCP server's prompt named like a built-in or TUI command above is left out. An extension's command named like one, which the commands answer marks with extension, takes its row instead, with its own description and hint, and runs in its place; it loads only when its manifest names that command in replaces (docs/extensions.md, "What a package holds"). An extension's command named like an alias takes that name the same way: its own row shows, and the built-in row drops the alias. An extension's command named like a built-in's name takes that row's aliases with it: they run the extension's command and show on its row. An extension's commands run
with the command driver command (docs/extensions.md, "Commands and
screens").
An unrecognised /name is refused: the terminal keeps the text in the
input box and shows the notice Unknown command /<name>. Type / for the list. A first word with another / in it, such as /usr/bin/env, is a
path and is sent as a message. On home, the same rule applies against
the built-in and TUI commands.
/add-dir <path> adds a folder to the session's boundary: it sends
add_directory with the path (docs/invocation.md, "Driver commands").
With no path, it shows the command's usage. There is no removal: an added
folder lasts for the session.
Clearing
/clear asks the hub to start a fresh session in the workspace of the session
on screen (its worktree included), with that session's model, thinking level
and credential label, and switches the screen to it with an empty
conversation. The new session builds its own prompt cache; nothing in the old
session's prefix changes. The new session takes the old one's card on the
rail, keeping its number. The terminal keeps the old session on screen until
the hub answers with the new session's id. It sends the old session's workspace
path unchanged.
Before the session has built its first prompt, its credential label is the one
its start named; with none named, the new session picks its credential as any
new session does. When the hub refuses or fails the start, the screen stays
on the session it shows, a notice gives the start's code and message, and no
close is sent.
The old session is sent close without now (docs/invocation.md, "What
each command does"): it takes no more prompts, finishes the turn and the jobs
in flight, and exits. Until it exits, home shows it as a live row marked
"CLOSING" ("The session list"); then it joins the project's exited rows, where
it reopens like any exited session. To stop a turn instead of letting it
finish, the person presses Esc before /clear.
When the old session waits on an approval or a question, a close without
now would wait for the answer, so /clear asks first, in an overlay
("Look", "Overlays"): the title "Clear", then "review #688 waits on an
approval." dim, then two choices, "Enter" to clear anyway and "Esc" to stay,
with Enter's focused. Clearing anyway sends close with now, which drops
the wait. A wait that begins after /clear asked nothing keeps the close
polite: the old session's request waits in the queue for an answer.
Logging in
/login logs in from the terminal with the same flow as fiber login. It
opens an overlay ("Look", "Overlays") titled "Log in" with a ✕: the providers under
"Providers", each tagged browser for OAuth or key for an API key, then
the extension credentials under "Secrets", the first row focused. Providers
with a usable credential come first, each marked "✓
On a remote terminal, login runs on the hub and stores its credential in the
hub's Fiber home. OAuth always uses the device-code step below; Esc cancels
the hub's login. The reviewer step lists the hub's models.
Once a provider is picked, each step replaces the whole overlay; nothing is
added under the list. The title is the provider's name and the list is not
drawn. The steps keep the provider list's height and share one width, so the
overlay does not jump between them; the URL is cut to fit rather than
widening it. Esc goes back to the provider list.
The browser wait. OAuth opens the browser and also shows the URL to
copy, for SSH: "Open this URL to log in to anthropic:", the URL cut from
the left to keep its tail, and "Waiting for the browser…" dim. Footer:
"y copy URL · Esc back".
Device code. "Enter the code {code} at this URL to log in to {name}:",
the code shown whole across wrapped rows, the URL cut from the left, and
"Waiting for the browser…" dim. Footer: "y copy URL · Esc back"; y copies
the whole URL.
Key entry. "Label (--as): default." and "Key for google:", the key
masked as dots with the cursor ("The input box"). Tab moves between the key and the
label. Footer: "Tab key or label · Enter submit · Esc back".
Done. "✓ Logged in to anthropic." in success. Footer: "Esc back".
Failed. "Login to anthropic failed: token expired.", the reason in
error. Footer: "Esc back".
Reviewer. After the key is stored, and after a browser login stores
its credential, the provider's models with the saved pick preselected,
else the package default: "1) fast-1", the saved row marked
" (saved)", or "Saved reviewer gone is not listed; Enter keeps it."
when the pick left the list. With nothing preselected no row is
highlighted until the person moves or clicks; Enter saves the highlighted
row, or the kept pick, and stays open otherwise. An empty list keeps the
login with a note naming the provider; a failed save keeps it with an
error naming the key. Footer: "↑↓ move · Enter save · Esc back". Esc
returns to the provider list writing nothing.
Logging out
/logout logs out from the terminal with the same delete steps as fiber logout. It
opens an overlay ("Look", "Overlays") titled "Log out" with a ✕: the providers under
"Providers", one row per stored or configured label with the default marked,
then the extension credentials under "Secrets", the first deletable row focused.
A row whose key comes from an environment variable, a file or a command is dim
with its source, and Enter on it does nothing, as on a heading or the note.
Enter on a deletable row asks for confirmation, naming the provider and the label,
and, when other providers read the same stored directory, naming them: "Delete
acme/work?" with "Also used by: beta" below it. The confirm keeps the list's
height and shares its width, so the overlay does not jump between the steps.
Footer: "Enter confirm · Esc back"; Esc goes back to the list deleting nothing.
Confirming deletes the stored file only, leaving providers."<name>".credential as
is, then re-lists the rows with the overlay still open: the deleted row is gone,
and "Removed credentials/acme/work." shows below the list, with ", which beta also
reads" when siblings share the stored directory. When a configured source covers
the deleted label its dim row remains, and later sessions use that source. A
failed delete keeps the row with the seam's message below the list. Footer on the
list: "↑↓ move · Enter delete · Esc close".
Quit
Ctrl+C clears, then quits. It clears a draft in the input box. With the
box empty, it says "Press Ctrl+C again to quit", and a second press within
about a second quits. It never interrupts a turn on its own; Esc does that.
Quit is a second Ctrl+C, or /quit, /exit. With no session working, meaning
no turn, job or delegate running, the terminal exits without asking. With
some working, it asks in an overlay ("Look", "Overlays"): the title
"Quit", "2 sessions working" dim, then three choices, "Enter" to leave them
running, "c" to close all and "Esc" to stay, with Enter's focused. The
footer reads "click a choice · they keep running meanwhile".
Enter, the default, leaves them running. The terminal closes its
connections, and each session follows the lifecycle rules
(docs/invocation.md, "Lifecycle").
"Close all" sends each working session close with now. The prompt says how many of them are also
open elsewhere: a session's clients on its session_status, less the terminal's own full connection to it when it holds one.
Stopping one session is /close, the ✕ on its live home row, or Delete on
its focused home row or rail card. It sends close with now, which ends
its turn, stops its jobs and delegates, and exits it
(docs/invocation.md, "Shutdown"). Delete asks first, in an overlay: the
title "Stop ?", a dim line that reads "working", "open elsewhere",
both as "working, open elsewhere", or nothing, then two choices, "Enter" to
stop and "Esc" to cancel, with Enter's focused. The footer reads "click a
choice". The line is counted as the quit prompt counts, once, when the
question opens, and the overlay never live-updates. It draws over the
conversation when asked from a rail card. Enter sends close with now;
when the stopped session is the one on screen the terminal goes home, and
stopping another card leaves the screen as it is. Esc, the ✕ and a click
outside the frame close the question and send nothing. With the link down
Delete opens nothing, and Enter does nothing and leaves the question
open. If the session left while the question showed, Enter sends nothing
and closes it.
Stopping every session is /close all, on home or over a session. It asks in an overlay: the title "Close all", "2 sessions, 1 working, 0 open elsewhere, 1 keeper" dim (live top-level sessions on this hub, how many of them are working, how many are open elsewhere, counted as in the quit prompt, and the keepers of gone sessions the hub's feed names, docs/tools.md, "The keeper"), then two choices, "Enter" to close all and "Esc" to cancel, with Enter's focused. The footer reads "click a choice". Enter sends each live top-level session close with now and the hub a command stopping each of those keepers, as fiber stop stops them (docs/invocation.md), and leaves the terminal on home; Esc closes the question. With no live session and no keeper it opens nothing and says "No sessions to close."; with the link down it opens nothing and keeps the draft. /quit straight after it exits without asking once those sessions have left, since none is working. Quit's own behaviour does not change.
Getting the person's attention
When any live session starts waiting on the person, for an approval, a
question or a finished turn, whether or not it is on screen, the terminal:
sends an OSC 9 desktop notification where the terminal supports one, and a
bell elsewhere. Support is read once at start: Ghostty, iTerm2, kitty or
WezTerm, by TERM_PROGRAM, TERM or KITTY_WINDOW_ID, and no tmux or
screen in between (TMUX and STY unset), since a multiplexer swallows the
escape. The text is "Fiber: needs you: ", or
"Fiber: finished", with the session's name, or its id when it has
none, cut to 60 characters, the summary cut to 120, and control characters
dropped.
shows the state in the terminal title: "! fiber · approval", "! fiber ·
question" or "! fiber · waiting" while that session still waits, and
"✓ fiber · finished" after a finished turn until the next key or click. The
latest attention wins, and the title goes back to normal once nothing it
names applies.
Each can be turned off: tui.attention.notification, tui.attention.bell and
tui.attention.title.
Mouse and hover
Mouse reporting is modes 1000, 1002, 1006 and 1003, every motion. Mode
1004, focus reporting, is also on for Quota queries ("The panel"); restore
turns it off. Hover
highlights the click target under the pointer. The highlight is instant, with
no transition. A frame redraws only the rows that changed.
tui.hover turns hover off, which drops mode 1003.
Measured in the prototype on macOS arm64
(research/tui-prototype/README.md,
"Hover's cost"): a still pointer costs nothing; each cell the pointer crosses
costs about 115 µs; each change of target costs one frame, about 1.8 ms and
255 bytes; a fast sweep costs 6.8% of a core. The timings do not carry over to
Linux; the byte and frame counts do.
Measured in Fiber on macOS arm64 (Darwin 25.6.0) with the hover jig,
cargo run --release -p tui --example hover -- crates/tui/examples/hover.jsonl,
at 160 by 48, 20,000 motion reports per case, the median of 5 runs, with
truecolour themes: a still pointer, and a pointer moving along one target,
wrote 1 frame and 135 bytes in 20,000 reports; a change of target on every
report wrote 20,000 frames and 2,590,000 bytes, painted with the theme's
colours; a fast sweep over a conversation whose lines are targets wrote 1,458
frames and 568,722 bytes in 20,000 reports.
Measured in Fiber on Linux x86_64 (7.3.0-9-generic, a 16-core, 24-thread 13th Gen
Intel Core i7-13700T, load average 1.25 to 3.05 across the runs) with the
same jig, command, size and runs: a still pointer, and a pointer moving
along one target, wrote 1 frame and 135 bytes in 20,000 reports; a change
of target on every report wrote 20,000 frames and 2,590,000 bytes; the
fast sweep wrote 1,458 frames and 568,722 bytes in 20,000 reports.
Look
Surfaces, not lines. The person's messages, each turn's card, code
blocks, the compaction band, the input box, the approval panel, the question
form, the search box, each panel card and every overlay sit on their own
background tint,
with half-block edges (▄ above, ▀ below) and no borders. An edge's cell
takes the surface's colour over the colour around it: the terminal's
background in the conversation, the turn's tint for a code block inside a
card, the panel tint for a panel card.
A stripe marks state on the side its surface is anchored to: ▌ on the
left for the input box, a running or finished job, an approval and a
question form; ▐ on the right for the person's prompt bubble. An overlay
has no stripe. The stripe is one unbroken bar, because ▌ and ▐ fill half of each cell as Ghostty draws them.
Where a terminal cannot draw it unbroken, there is no stripe. Fiber draws
stripes in Ghostty, WezTerm and kitty, and not inside tmux or screen;
elsewhere the stripe's cell keeps its tint.
Colours come from the theme, in truecolour where the terminal has it:
COLORTERM of truecolor or 24bit, or a TERM of xterm-ghostty,
xterm-kitty, wezterm or one ending in -direct, which survives SSH where
COLORTERM is usually dropped. Anywhere else the terminal has 256 colours,
and each colour is the nearest entry of the xterm palette: the neutral tints
(background, panel, surface, surface_raised, turn, prompt,
code, approval, rule, hover) take the grey ramp, the other tints take
the colour cube so they keep their hue and an alert stays red, and text
takes either. The terminal's
own 16 colours are never used.
NO_COLOR set and not empty turns colour off: every role is the
terminal's default colour. Bold, dim, reversed and underline stay, so focus,
selection, matches and state words still show. With no tint there is no
surface to see, so each surface with half-block edges is drawn instead as
a thin box, ┌─┐ above, │ on each side and └─┘ below, dim, in the edges'
rows and one column on each side, so a rail card's text is two columns
narrower. The person's prompt bubble is the exception: its edges draw as
blanks and its rows stay.
Markdown in replies:
Headings are bold in heading, their # markers stripped.
Paragraphs are in the text colour, **bold** is bold with no colour of
its own, and inline code is in info, with no tint and its backticks
stripped.
A bullet is "• " in accent, its wrapped lines hanging two columns in.
A code block is a code slab with ▄ and ▀ edges. Its first row is the
language dim, one column in, and "click to copy" dim, right-aligned. Each
line is its number right-aligned in four columns in rule, two spaces,
then the code with syntax colours; a comment is italic as well.
A table's header row is bold, and under each column is a ─ rule in
rule as wide as the column; columns are three spaces apart, and the
rules break with them. A column whose cells are all numbers is
right-aligned, in the text colour.
rust click to copy
1 pub fn try_lock(path: &Path) -> Result<Lock> {
2 // one holder at a time
3 let file = File::create(path)?;
Crate Tests Lines
───── ───── ─────
hub 41 3,120
tui 212 9,804
Overlays
Every surface drawn over the screen shares one frame: the
key map, the quit question, the close-all question, the stop question, the
hooks install offer, the /delete question on an attached session, the
session-list delete question on home, the workspace picker, the /login
overlay, the Ctrl+R panel, a notice's whole text, the import report, the
/ and @ completion panels, and the model picker inside its view.
The frame is a surface slab with a ▄ edge above and a ▀ edge below,
and no border glyphs. Each row that holds text opens with two blank
columns and ends with two blank columns, with no stripe. One blank
row sits inside each edge, so no text touches either.
The width is the content's plus those four columns, kept between 40
and 150 columns and never wider than the screen. Content that wraps is
wrapped at a preferred width first and the overlay shrinks to what the
wrapped content needs: 71 columns for a question or notice, 55 for the
workspace picker, and 96 for the model picker and the completion panels,
less four columns on a narrower screen.
Placement. An overlay is centred across the area it covers. A question,
a notice, the Ctrl+R panel and the workspace picker are also centred down
it, unless that would cover the input box's top row: then the workspace
picker, when it fits there, sits with its bottom edge on the row above the
box. The key map docks at the bottom, full width. The completion panels
sit above the input box, and the model picker under its view's top row.
The overlay's side margins are blank, with no tint, so the screen behind
reads around it.
Rows. A title, when there is one, is bold in accent, with a ✕ or a
count dim at its right end. The title, body and footer keep one blank row
between them; the body's sections keep their own blank rows.
Choices. Each choice row starts with two columns of gutter. A row of
keys and descriptions keeps the keys in one column as wide as the widest
key, two spaces, then the description dim; a description that wraps hangs
under its own start. The focused choice has "› " in its gutter, reads bold
throughout, and sits on a full-width bar in accent with its text in
#000000. Exactly one row is barred.
The footer is dim and aligned left with the body, never centred. It is
a legend: each key bold and its label dim, joined by " · ". It never
repeats a key the body already lists as a choice; where the body lists every
key, the footer says what the mouse does instead.
▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
▌ Quit ✕
▌
▌ 2 sessions working
▌
▌ › Enter leave them running
▌ c close all
▌ Esc stay
▌
▌ click a choice · they keep running meanwhile
▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
Themes
Fiber ships a dark and a light theme. A person adds their own as files in
Fiber home, an installed extension can carry more, and either is picked in
/settings, which writes tui.theme. /theme opens the same theme picker:
moving focus previews each theme live, Enter saves the choice, and Esc or
the close button restores the theme that was showing.
/theme <name> sets the named theme at once, saving tui.theme. With no
theme set, the theme follows the terminal's light or dark appearance and
switches when the terminal reports a change.
A theme sets colours only. It gives each colour role a value, and an
extension's spans name the same roles ("What a renderer returns"). Anything
bigger goes through "Extension seams".
The roles, in order, with each built-in theme's values:
Role
What it colours
Dark
Light
text
the full text colour: replies, the draft, anything with no role of its own
the terminal's foreground
#1f2328
muted
what the doc calls dim: READY, labels and hints, summary lines and results, block quote bars, grips, the logo's counters
text, dim
text, dim
accent
bullets, the logo's mark, WORKING and the rail's spinner, a running job's stripe, the prompt and input stripes, the model's name, answered questions' headers, a quota bar, an overlay's title and selection bar, a project header's name, links and the ▣ line
#6eaafe
#0969da
heading
markdown headings
#ff9f43
#bc4c00
success
a completed call's ✓, a finished delegate's ✓, a finished job's stripe when it succeeded, a login's ✓
#6eaafe
#0969da
warning
RETRYING and its spinner, a rail card's context bar from 60%
#ff9f43
#bc4c00
error
CRASHED, a failed job's stripe, an escalation's stripe, "irreversible" in an approval's header, a rail card's context bar from 85%, a down MCP server, a quota nearly spent, tool results in the context breakdown, a failed login's reason
#ff5d73
#cf222e
attention
NEEDS INPUT, what a card waits on, a standing ask's stripe, the working line's spinner and glimmer, a running call or delegate, the permission mode, the thinking level, the compaction marker, "steer", the steering card's title, stripe and marks, notices, approvals put aside, the pill's label, the search box's ⌕
#ff9f43
#bc4c00
added
lines added: an edited file's +N, added lines in a diff
#73c991
#1a7f37
removed
lines removed: an edited file's −N, removed lines in a diff
#ff5d73
#cf222e
code_text
code with no syntax role
the terminal's foreground
#1f2328
keyword
keywords
#6eaafe
#0969da
string
string and character literals
#ce9178
#a31515
comment
comments, which are also italic
#7a7a8a
#6e7781
number
number literals
#b5cea8
#116329
function
function and macro names
#7dd3fc
#0b7285
type
type names
#7dd3fc
#0b7285
constant
constants: true, null, ALL_CAPS names
#7dd3fc
#0b7285
operator
operators
the terminal's foreground
#1f2328
info
inline code, a call's kind, an approval's tool name and rule prefix, the input box's › and the workspace picker's, "Copied", the context bar's fill
#7dd3fc
#0b7285
secondary
the git branch, the compaction band's label, the question form's stripe, title and marks, the delegates' ◆
#b39ddb
#6f42c1
rule
rules, line numbers, a bar's empty cells, the pill, a grip's column under the pointer, "Chat about this"
#3a3a4a
#d0d7de
scroll
the scroll bar's thumb
#808080
#b0b7bf
background
every cell of the conversation and of a swapped view that no surface covers
#0c0c11
#ffffff
panel
the rail's and the panel's regions
#0c0c11
#f6f8fa
surface
the input box, the panel's cards, the steering card, the search box, a swapped view's top row, overlays, the rail's working cards
#1a1a22
#eaeef2
surface_raised
the card on screen, a hovered card
#3a3a4a
#d0d7de
card_retrying
a rail card in RETRYING
#262014
#ebe5d9
card_needs_input
a rail card in NEEDS INPUT
#241a10
#efe5db
card_ready
a rail card in READY or IDLE
#121217
#e8e8ed
card_crashed
a rail card in CRASHED
#201114
#eedfe2
turn
a turn's card
#101017
#f3f5f8
prompt
the person's prompt bubble
#343541
#dde3ea
code
code blocks
#181821
#eff1f4
compaction
the compaction band
#1f1a2e
#efe9f9
approval
the approval panel for a standing ask, and the question form
#1a1a22
#eaeef2
alert
the approval panel for a reviewer's escalation; red in both built-in themes
#501c20
#ffd7d9
hover
the click target under the pointer where it has no tint; a target on a tint is drawn with that tint lifted: 0x14 on each channel away from the page, lighter on a dark tint and darker on a light one (a tint whose channels average below 0x80 is dark)
#1e1e26
#e3e7ec
selection
selected text
#264f78
#b6d7ff
match
a search match, its text white
#5a4a1a
#fff1a8
match_current
the current search match, its text black
#ff9f43
#ffd67e
In the dark theme text, code_text and operator are the terminal's
own default foreground, and muted is the text colour drawn dim. They stay
the default at 256 colours. The page is Fiber's own: background is
#0c0c11, the panel colour, so the conversation, every swapped view, the
rail and the panel read as one field, and the terminal's own background
shows nowhere. At 256 colours background takes the same entry as panel.
A theme file may still give any of them a #rrggbb.
The light theme paints its own text and page: text, code_text and
operator are #1f2328 and background is #ffffff, so it looks the same
in any terminal. At 256 colours its page is the colour cube's white, 231,
which the grey ramp lacks. A tint whose nearest entry is 231 takes the grey
ramp's lightest, 255, so every tint stays visible on the page.
A stripe takes its state's colour, and the logo's five letters step through
heading, accent, string, type and keyword.
A theme is a file, themes/<name>.json in Fiber home or in an installed
extension (docs/extensions.md, "What a package holds"), and tui.theme
names it by <name>; dark and light always name the built-ins:
base, dark or light, gives every role the file leaves out, so a theme
keeps working when a role is added. roles maps role names to #rrggbb. The
file is strict: any other key, an unknown role or a value that is not
#rrggbb refuses the whole file. A file that is missing or refused shows one
notice naming the theme and the reason, and the theme follows the terminal's
appearance. Nothing writes the bad name back. Fiber home's file wins over an
extension's, and between extensions the first by directory name in
extensions/ wins; /settings lists each name once. Only a missing file
passes the name on: a file that is there but cannot be read or is refused is
the theme. A damaged extension's themes are left out, as are a switched-off
extension's (extensions."<name>".enabled is false): they are not listed,
and a tui.theme naming one reads as a missing file. Colours are given once, in 24
bits, and the 256-colour form is computed ("Look").
Reduced motion
Every animation has a still form. tui.reduced_motion turns reduced motion
on; detection is not built yet (see #1506).
Screen readers
Not built yet: see #1506.
Images
Where the terminal speaks kitty's graphics protocol (Ghostty, kitty, WezTerm),
images show inline: an image a tool returned, in its ledger row, and a pasted
image, with or without text, in the prompt bubble.
Kitty's graphics protocol takes only PNG, so the loop converts (fiber image --png /dev/stdin with the decoded bytes streamed to its standard
input): the terminal spawns one image child at a time and keeps that one
worker on the loop (each completion frees it for the next queued
conversion), and transmits only after converting. The child's standard
output must stay under the 32 MiB cap, or the child is killed and the
image fails; refusal and other failures reuse the child's stderr, kept to
16 KiB and trimmed of trailing whitespace, in the existing notice. The
draw never waits on the child: conversion runs on a worker thread and each
completion arrives as loop input. A completion from an earlier session's
generation is dropped, and a forgotten image never transmits.
An upload holds the loop for at most one chunk: a writer sends each
image's chunks and then its placement while the loop reads input and
draws. Frames go out between whole chunks, so a frame drawn while an image
transmits shows that image's rows blank, at their size, until it lands.
Images transmit and place in the order queued, and no other image command
goes between one image's chunks except a delete, which goes at the next
chunk boundary: an image it removes sends nothing more, and an unrelated
upload it interrupts is sent again whole after it. Quitting while an image
transmits sends the delete for that image at the next chunk boundary and
nothing more of it. A failed write to the terminal is the terminal failing:
every pending image is dropped and nothing more is written.
An image is at most 40% of the conversation's width and 12 rows tall,
keeping its proportions. A click opens it in the system viewer, from a
copy the terminal writes to cache/images/ in Fiber home
(docs/state.md).
Under its grid an image has a caption, its one line ▣ <file> · W×H, and a
click on either opens the viewer. In the prompt bubble a caption wider than
the bubble shortens the file name first and keeps the size.
A PNG shows inline as stored. A JPEG or WebP shows inline when the
launch names the fiber executable to convert it through fiber image --png; otherwise, like any other type, it is its one line.
A steering message's images are one clickable line each under its text,
even where images show inline.
The terminal holds the image and moves it with the text, through kitty's
Unicode placeholders. Fiber keeps no decoded image and sends nothing again
on a scroll.
When the session changes, Fiber deletes the previous session's inline
image placements before drawing the next session and does not write those
placements again; images the next session presents are written for the new
session.
Handing the terminal to another program, such as the editor, abandons an
image upload in progress at a chunk boundary, closing it first. On return,
the alternate screen has no images, so every image on screen is sent again
whole.
An image part in the log carries its width and height, so paging counts its
rows without decoding it.
Elsewhere an image is one clickable line, ▣ screenshot.png · 1280×800, in
the link look ("Links"); in a ledger row it sits under the call's row.
An image the terminal cannot show, because its file is missing or too
large or the terminal refused it, is its one line, with a notice saying
why, and is not asked for again in that session.
iTerm2's protocol and Sixel make the client redraw an image on every scroll,
so only the logo, drawn once, uses them. tui.inline_images turns inline
images off.
History and paging
The terminal holds a window of rendered history and asks the session for more
as the person scrolls, with the history command, which reads by seq over
the session's offset table (docs/invocation.md, "Driver commands";
docs/events.md, "Resume").
Opening reads the tail before the first frame, then counts history and
makes one streaming pass. The
terminal subscribes at summary and asks history, with no from_seq,
for the session's last lines. The terminal checks each answer for
ascending, contiguous sequence numbers. It folds each eligible whole-turn
run into fresh pages. If an older answer enlarges the run before install,
the terminal rebuilds from fresh pages and discards the prior candidate.
It installs the newest candidate without another fold. The terminal asks
for older own-segment windows until the preview fills the screen up from
its last row, beginning at a turn's start. The first frame draws the
preview. After it, the terminal reads older windows down to the session's
seq 0 and each ancestor named by forked_from to the chain root, carrying
ancestor runs above the preview for the joint total. These count reads
never rebuild the displayed preview. A run that reaches seq 0 short of
the display crosses into its ancestors before the first frame instead. The
terminal then raises the subscription to full.
The pass goes over the session's lines as the full subscription sends
them. It builds the panel's cards and counts every row, keeping each
row's seq. No event is kept: each is applied to the panel's folds and
dropped. The pass renders no page for display.
The terminal opens a pass on a full acknowledgement with last_seq,
or on stream_reopened with last_seq (docs/events.md). It ends the
pass when it folds that seq. No last_seq means no pass is open, and
an empty log means the first frame draws no history.
A pass of any session the terminal holds at full, an open item's
included, blocks history. Until it ends, the conversation on screen
doesn't change: a frame draws the pages already held, and the panel
shows the cards folded so far. The scroll bar appears when the pass
ends. Scrolling, recounting at a new width, search and copy wait.
The one exception: rows that depend on turns before the held pages (an
orphaned job's completion, an automatic compaction's trigger, a ledger
toggled earlier, a message call to a delegate started or named before the
held pages: only rows of these kinds) may change in the frame where
the pass ends. An opening that fills only after crossing seq 0 draws
through the chain root, so the landing rewrites nothing across the seam.
If the own segment fills first, the count phase adds ancestors above the
preview without refolding its visible pages. On one segment the preview
holds the filled run and the pass counts the rest, so the landing adds the
rows above it. A tail or count read that is rejected or abandoned installs
nothing: the previous transcript stays and the busy indicator is left to
the live session, with a notice when the read was rejected.
EOF, stream_closed, a failed read, a disconnect and lowering
to summary end the pass too. The feed's session_left for a session
ends that session's pass. Waiting work then runs against what is held,
or fails as usual with no connection.
If stream_reopened for the session being waited on arrives during a
history wait, the wait ends at once; a reopening for any other
session leaves the wait alone. A history wait with no answer after
10 seconds ends as a lost connection, and the terminal reconnects as
it does after a disconnect.
Stashed lines fold in order before the new fold, whose lines are
never stashed. The late answer is discarded by its id, and the page
loads in a frame after the pass ends.
A rewound or moved session pages across its forked_from chain as one history,
cut at each continuation point. The terminal reads forked_from from the
session's session_started, asks history with session_id set to that
ancestor and to_seq set to its seq, pages that session the same way,
and repeats for each further ancestor. Pages, row counts, search and the
opening pass treat the chain as one history. The terminal never reads a
log from disk. land carries the preview's closed ancestor pages across
the swap the way it carries open items; a dropped ancestor page loads
again with history under its session_id, and the fold still replays
the own log only. Ancestor rows are counted by the same history
streaming before the scroll bar appears, never from the subscription:
"until the screen is full" governs the display phase on its segment,
and past a segment start the count phase keeps streaming to the chain
root.
Pages are cut inside turns, at step_started, about 64 lines each, and
never inside a tool group, so each page renders on its own.
The window is the pages on screen plus one screen of rows above and
below. Every other page is dropped.
Row counts are exact, measured in the opening pass and again when the
width changes. Every row has a stable index, which the scroll bar, search
matches and the selection share.
Pages load inside the frame that needs them. There is no background
loading.
Queued inputs share a frame by kind. Queued hub lines and ticks share
one frame in arrival order, up to 4,096 inputs, so a stream that never
empties still draws. A run of queued terminal reads shares one frame, so a
run of wheel steps draws once. A key, click or resize draws its own frame at
once, so click targets always come from a frame the person saw, and a key
that swaps the screen does not carry the next key's work.
Search streams the session's lines with history, rendering each page to text and keeping only its
matches. On a large session it does not run on every keystroke: it waits for
a pause in typing of a quarter of a second, or runs off the frame thread.
A selection's ends are row indices. Copying reads the rows between them,
rendering again any page dropped since the drag began.
Measured in the prototype on macOS arm64, on a session of 6,135 lines and
1,047 tool calls (4.4 MiB), built to match the longest of the owner's sessions
(research/tui-prototype/PAGING.md,
LARGE.md), and in Fiber by the paging
jig (docs/testing.md, "Jigs") on macOS arm64 (Apple M3 Pro), release build,
on a session it generates in the same shape: 10 turns, 965 steps with text and
1,051 tool calls, 8,074 lines, 4.7 MiB with the running turn below. Fiber's
session has more lines than the prototype's, because Fiber writes
step_started and text_completed lines the prototype's fixture does not
have. Its screen is 160 by 48; the session draws 2,915 rows in 120 pages.
Fiber's figures are the median of three runs.
What
Prototype
Fiber
Peak footprint, whole log folded against paged
36.7 MiB against 6.6 MiB
11.2 MiB paged, of which 4.7 MiB is the jig's copy of the session, standing in for the hub's log
Panel pass at open
18.7 ms
55.0 ms, the opening pass and the first frame
Counting rows
about 4 ms per MiB of log
in the opening pass; 12.1 ms to count every page again at a new width
Slowest frame that loaded pages
5.1 ms
1.1 ms
Search of the whole log
19.6 ms
188.3 ms
Estimated row counts moved the scroll bar's thumb by up to 17 cells in one row,
which is why counts are exact. The timings do not carry over to Linux; the
row, page and match counts do.
Also measured in Fiber, on the same machine:
Appending to the last page while a turn runs. A running turn of 30
steps, 481 lines with its deltas, fed one line a frame: the slowest frame
took 0.85 ms, and at most 5 pages held cards throughout.
A session ten times larger: 80,709 lines, 10,505 tool calls, 46 MiB.
The opening pass and the first frame took 580 ms, the slowest frame that
loaded pages 0.62 ms, and counting every page again at a new width 133 ms.
Peak footprint was 61.9 MiB, of which 46 MiB is the jig's copy of the
session.
Jumping the way dragging the scroll bar's thumb does. The scroll bar's
thumb does not drag, so the jig moves the top row to 20 rows spread across
the session, one frame each. The slowest frame took 1.9 ms, and 1.1 ms on the
larger session.
On Linux x86_64 the benchmark job (docs/performance.md, "Measuring", the
paging rows) runs the jig on every pull request. Its run of 7 October 2026
(GitHub Actions run 37700922577) gave, as the median of 5 runs: the opening
pass and first frame 673 ms, the slowest frame that loaded pages 3.0 ms, the
slowest jump frame 5.4 ms, counting every page again at a new width 61 ms, and
the slowest append frame 1.4 ms. The jig's session had 8,285 lines, 10 turns
and 1,051 tool calls, and the counts match macOS: 2,915 rows in 120 pages.
Peak resident memory was 8,796 KiB, the jig's copy of the session included.
Extension seams
An extension may change everything the terminal draws. It does this through a
TUI extension (docs/extensions.md, "Commands and screens"): Lua 5.4 scripts
that run in the terminal's process. Settled by
TUI extension seams.
The terminal is built from named slots. Each slot has a built-in renderer in
Rust, and an extension may replace it or add slots of its own. The machinery
around the slots stays the terminal's: paging, scrolling, selection, search and
the panel's scrolling. So every extension keeps what "History and paging" and
"Reading and copying" promise. A program that wants to draw the whole screen
itself is a separate client of the hub, not a TUI extension.
The slots
Not built yet (replaced input box; home, view, and overlay slots): see #688.
Slot
What it draws
layout
Where each region goes: the conversation, the panel, the working line, the steering queue, the input box, and any region an extension adds
home
Home
turn_card
A turn's card and its ▣ line
prompt
Only a person's prompt bubble: a non-driver message never calls it
reply
An assistant reply
group_line
A tool group's summary line
ledger_row:<tool>
A ledger row for the named tool
ledger_row
A ledger row for any tool without its own
thinking_line
A thinking line
steer
A steering message in its card
answers
The "you answered" rule after a question form
compaction_band
A compaction's band
error_line
A failed turn's ✗ line
notice
A notice
card:<name>
A panel card: session, changed_files, delegates, jobs, or one an extension adds. card:quota is not a slot: the Quota card stays built-in, and an extension reads quota through status_rows
working_line
The working line
steering_queue
The queued steering messages
input_box
The input box
input_status
The input box status row
status_rows
The input box's status line
view:<name>
A swapped view, built in or one an extension adds
overlay:<name>
An overlay an extension adds, drawn over the conversation
approval
The approval panel, draw-only
question_form
The question form, draw-only
repository_offer
The offer of what a repository ships, draw-only
A slot receives what its built-in renderer receives. Most of it comes from the
event stream, except whether the row is open, which the person's clicks and
keys set, and notices the terminal raises itself, such as a configuration or
I/O failure. Chrome slots may also read outside the stream: the branch comes
from git status, the cards follow the panel's configuration, and spend
falls back to the attached spend when the session reports none. A ledger row, for example, receives the call's name,
arguments, changed_by, status, exit code, duration, line count, changes and
error, folded from its tool_call_* and permission_resolved events, and a
message call's recipient: the recipient's description or name as the terminal
held it when the call folded, absent when it held none. No slot sees the terminal's internals. A ledger row's renderer draws what follows the step's six-column gutter and receives the width less 6; a renderer that returns no lines draws no row.
Each slot's input holds exactly what its built-in renderer reads. Every input listed here also carries flat, which is true in screen-reader mode when the terminal drops every style. Timestamps come as source values, never as elapsed strings. The person's own interaction state (selection, open or closed) is included only where the built-in draws it. An optional key is absent when it does not apply, never null. The terminal's internals stay out: no layout, width fit, cache, spinner glyph or motion clock.
A replacement owns its rows whole: where the built-in row carries one target over the row, each replacement line keeps it. A target placed on part of a row goes away when the extension owns those rows. A notice keeps its notice target on every replacement line and its dismiss target spans those painted lines. A notice replacement with more lines than the notice rows left keeps its first lines in order and drops the rest, as a line too wide is cut; the rows it paints are the rows it takes, and its targets span only those. An error_line keeps its failed-login target on each line. A steer replacement drops image-line targets because it owns those lines. A prompt keeps the target for a single image on each replacement line and drops targets for several images. A writing compaction_band has no target, and reply, turn_card and answers remain without targets. A steering_queue replacement drops the per-message edit and drop targets, and a card replacement drops the panel targets that differ from row to row; keys still do everything the dropped targets did. The working line keeps its interrupt target, and a card keeps the one target shared by every row it draws, on each replacement line.
turn_card draws a turn's card whole: its prompts, every entry, and its
ending. A replaced card is drawn whole by the extension, so no nested slot
runs inside it; prompt draws only when the card itself is built in.
Field
What it holds
prompts
The turn's person's prompts in order — only Origin::Driver messages — each with the prompt slot's text and images (path, width, height in pixels)
entries
The card's items in order, each tagged with a kind and carrying the slot input shown below
started
When the turn started
calls
How many model calls the turn made
usage
The turn's totals: tokens (input, cache_read, cache_write, output), cost, subscription_cost
ended
How the turn ended: outcome, ended_ts, and on a failure its error (code, message); absent while the turn runs
running
Whether the turn is still running
The entries carry these slot inputs and extra fields:
Kind
Fields
reply
The reply input: text (Markdown included)
steer
The steer input: text, images, ts
message
source (fiber, session or extension), label, text, images, ts
group
The group_line input, plus cut and sections
aside
No slot: {kind = "line", text}, {kind = "warning", message}, or {kind = "orphans", jobs, open}; each job has name and message
band
The compaction_band input: trigger, ts, state; a done state carries before and optional after context sizes
answers
The answers input: outcome, parts, note?, ts?; each part has header, text, skipped
A session message's label is the sender's current non-empty session name,
when one is known, else its session id. An extension message's label is its
extension name. An unknown kind is skipped.
prompt draws only a person's prompt bubble: a non-driver message never calls it, and goes in entries as message instead.
Field
What it holds
text
The prompt's text
images
Its images in order, each path, width and height in pixels
reply draws an assistant reply.
Field
What it holds
text
The reply's text, Markdown included
thinking_line draws a thinking line.
Field
What it holds
text
The thought's text
started
When the thought started
ended
When it ended; absent while it streams
open
Whether the thought is open
An empty thinking_line result draws no row and no opened body.
group_line draws a tool group's summary line.
Field
What it holds
running
Whether the turn runs and this is its open group
calls
The group's calls in order, each with the call fields a card's group entry carries
streaming
The calls the model is still emitting, each with message, index, name and text
thoughts
The group's thinking blocks, each with text, started, ended and open
failed
The retried model calls, each with its code and attempt
first
The earliest timestamp the group spans
last
The latest timestamp the group spans
open
Whether the group's ledger is open
steer draws a steering message.
Field
What it holds
text
The message's text
images
Its images in order, each path, width and height in pixels
ts
When it landed
answers draws what a form left: the answers or the decline.
Field
What it holds
outcome
given or declined
parts
Each question's part, in field order: its header, text, and whether skipped
note
The note on the whole form, when one was left
ts
When the form was resolved; absent when declined
compaction_band draws a compaction's band, without its note.
Field
What it holds
trigger
What the compaction runs at
ts
The band's timestamp
state
writing, done, or unchanged with cancelled; a done state carries before and optional after context sizes
error_line draws a turn's failure line.
Field
What it holds
code
The failure's code
message
Fiber's own sentence
provider
When present, the provider's name, optional HTTP status, and message
For example, for a failed login, clicking any line an extension returns for this row opens the login view.
notice draws a notice, in the conversation and on home. The
terminal's own notices carry the same fields: a configuration or I/O
failure raises the same input an extension draws.
Field
What it holds
code
The notice's registry code
text
The notice's message
The extension_failed switched-off notice always draws built-in: a
notice extension cannot hide its own switch-off failure.
working_line draws the working line. It reads the session whose
conversation is on screen: the attached session, or in a delegate's view the
delegate.
Field
What it holds
started
When the turn started, as the turn card's value; absent before the turn starts
retry
The pending retry: code, attempt, last_attempt, delay_ms and ts; absent otherwise
A replacement that returns no lines hides the working line. The built-in
retry line carries no interrupt target but Esc still interrupts; a
replacement keeps one interrupt target over each line's full width either
way.
steering_queue draws the steering card ("Steering"): its slab and
stripe, the title row, one entry per message and the key hint. A
replacement's lines take the card's place, with no slab and no click
targets; the keys still pick and drop messages. A replacement that returns
no lines hides the whole card.
Field
What it holds
messages
The queued messages oldest-first, each with text, images (path, width and height in pixels), droppable (sent while steering), selectable (droppable with no image) and selected (the person's ⌥↑/⌥↓ choice)
Nothing draws and no renderer runs on an empty queue.
input_status draws the input box's status row, under its rule. A
replaced input box is drawn whole by the extension, so input_status draws
only when the input box itself is built in. A replacement draws one line, and
further lines are dropped. A replacement keeps one target, the Session
status view, over the row's full width. A replacement that returns no lines
leaves the row blank; the rule stays.
Field
What it holds
workspace
The workspace's path
mode
The permission mode
model
The model
thinking
The thinking level
context
tokens and window
status_rows draws the input box's status line, while the panel is not
shown. Like input_status, it draws only when the input box itself is built
in.
Field
What it holds
cards
The cards the narrow layout shows, in order
session
The same input card:session draws
changed_files
files, every changed file in the order the built-in ranks them
delegates_running
How many delegates run
jobs_running
How many jobs run
widgets
The extension widgets on screen, each with extension, widget and lines
waiting
How many sessions wait; absent at zero
quota
The quota answer (docs/events.md, "Payload types"): an array ordered by provider name, then credential label, each with provider, credential and windows or credit or unreachable, plus notice_at; absent when the built-in draws no Quota segment
Not built yet (extension card replacement): see #688.
card:<name> draws one panel card through its slot: session,
changed_files, delegates, jobs, or one an extension adds. A widget's
narrow row and a running delegate's narrow row draw through the same slot
with the same input. Its narrow form caps what the built-in shows, as the
five-file cut does, and the replacement inherits the cap.
card:session draws the Session status card:
Field
What it holds
workspace
The workspace's path
branch
The branch from git status; absent when unknown
model
The model
thinking
The thinking level
thinking_now
Whether the model is thinking now
context
tokens, window and trigger_at
spend
cost with tokens (input, output, cache_read, cache_write) and subscription_cost; when the session reports none, the attached spend falls back to cost alone; absent when there is no spend at all
budget
The spend budget; absent when unset
cache_expires
When the prompt cache expires, as ts, from session_status (docs/events.md); absent before the first request
speed
The last reply's output speed in tokens per second; absent before the first timed reply
turns
How many turns the session ran
tools_down
The tools that are down
waiting
How many sessions wait; absent at zero
card:changed_files draws the changed-files card:
Field
What it holds
files
Every changed file in the order the built-in ranks them, each with path, added and removed
card:delegates draws the delegates card:
Field
What it holds
delegates
Running delegates in start order first, then finished ones in start order, each with job_id, description, harness, model, calls, step and started; a finished one also carries outcome and ended; each has cost when spend was reported, with billed (number or null) and subscription (number) copied from its spend
card:jobs draws the jobs card:
Field
What it holds
jobs
The jobs, each with job_id and description
open
Whether the person opened the jobs list
card:<extension>/<widget> draws an extension widget's card:
Field
What it holds
extension
The extension's name
widget
The widget's name
lines
The widget's lines
open
Whether the person opened the widget
Not built yet: see #688.
layout places regions and never draws them. It receives the screen's size
and returns a rectangle for each region it shows. A region it leaves out is not
shown. A layout does its own narrow layout and shedding. The "Fiber needs
40×10" floor stays the terminal's.
Not built yet: see #688.
The three draw-only slots decide how an approval, a question form or a
repository's offer looks, never what it sends. An extension may restyle and
reorder their choices. It cannot add, remove or relabel one, and its key
handler never sees their keys. The choices, their keys and the reply they
send stay the terminal's, so an extension never approves a tool call
(docs/extensions.md, "Host calls").
A TUI extension also binds keys to its own commands or to built-in actions, and
adds slash commands, which join the one list ("Slash commands"). A theme stays
a file that sets colours only ("Themes").
What a renderer returns
A renderer receives the slot's input and the width, and returns lines. Each
line is a list of spans:
fg and bg name one of the theme's colour roles, such as success,
muted or accent. There are no hex colours and no escape codes, so every
extension follows the theme, a light or dark switch and NO_COLOR. The
roles are listed with the themes and belong to the extension API.
link makes the span a link, opened on click as "Links" says.
click makes the span's cells a click target with that id ("Input and
focus").
The terminal builds the cells and the plain text from the same spans, so what
is drawn and what is selected, copied or searched cannot differ. It measures
width by grapheme cluster and cuts or pads each line to the width, so an
extension cannot overflow its slot or move its neighbours. A span whose text
holds a control character is the wrong shape. So is a link whose scheme is not http, https or mailto, and an fg or bg that is not a colour role.
In the screen-reader mode ("Screen readers") the input carries flat = true.
The terminal drops every style, and a renderer should return one line for the
item.
A renderer may call builtin(input, width), which returns the built-in
renderer's spans. An extension that only adds a badge to a row decorates the
built-in rather than drawing the row again.
How a TUI extension runs
From the terminal's own Fiber home only. A TUI extension belongs to the
client. A repository's packages bring session halves only, and their TUI
extensions never load (docs/extensions.md, "Client halves").
One VM per extension, for every session. Every callback and event
handler receives the session_id it is for, and the extension keys its own
state by it. Timers belong to the extension, not to a session. on_focus
runs with the session_id when the session on screen changes, and
whole-screen slots (layout, input_box, keys, slash commands) receive the
session on screen.
Only for a session that loaded its session half, at a version inside
the range the TUI extension declares. For any other session it draws
nothing and the built-in rendering stands, with one notice naming the
extension and both versions. A later extensions_loaded switches it on or
off without a restart.
On the terminal's thread. Each TUI extension has its own Lua VM there.
Its event handlers and timers run as coroutines, and a host call suspends
the coroutine until the reply arrives through the terminal's event loop, as
on the session side. Between callbacks the VM is idle, so a renderer is
always called at once and answers at once. A renderer makes no host call.
Every callback declares its timeout. Renderers, key and click handlers,
the layout, event handlers, timers and loading alike, as on the session side
(docs/extensions.md, "How an extension runs"). The same two-stage
instruction hook enforces it.
Loading comes before the first frame. A replaced layout or input box
changes the first frame, so the terminal loads its TUI extensions before
drawing it ("Performance"). Reading, compiling and running the entry script share the loading timeout, as on the session side. An extension that passes it is switched off, and the frame goes ahead without it.
The renderer is a trait the terminal defines.tui defines a
Renderer trait, and main adapts the extensions Lua VM to it, so tui
depends on no crate that holds the VM (docs/architecture.md, "The call
rules"). tui tests use a fake renderer.
Each drawn item is cached by its input and the width. Its spans name
colour roles, which the theme resolves as the frame is written, so a theme
change runs no renderer. A renderer runs again only when its input, the width,
or an on-screen animated item's or notice's frame changes ("Animation"), so an
unchanged frame calls no Lua: one call per cache miss or frame advance, none on a hit.
The cache lives with the paging window and is dropped with its pages.
The key also includes the page's session and index, the selected extension,
and its session-half version when it has one. A change to any of these
reruns the renderer; an unrelated session-half change does not. Failures
use the same key without width.
A range-bound client half stays inert without notice until the session's
first extensions_loaded. An omitted or out-of-range half stays inert
with one extension_incompatible notice per TUI extension and session-half
version until /reload; omission counts as not loaded. The notice names
the TUI version and the session-half version, or not loaded.
A client half with no session half, such as a layout or a ledger row for a built-in tool, draws for every session.
Home has no session. Its notices reach extensions without one: the
input carries no session_id key (Lua reads nil), never another
session's id and never an empty one. A client-only half draws for every
home notice; a range-bound half stays inert without notice until the
session's first extensions_loaded, as on a session it has not seen.
A TUI extension binds whole-screen keys with fiber.key.fiber.key(name, { timeout, run }) runs run for the key when nothing
built in should, and fiber.key(name, { action, variant }) dispatches a
built-in action through its checked canonical event for that variant
(docs/extensions.md, "Whole-screen keys"). run receives exactly
{ session_id = "…" } and returns true when it handled the key;
anything else falls through to the built-in key map. Only true
handles: false and nil do not, and any other value is the usual
wrong-shape failure. A timeout switches the extension off until
/reload, exactly as a still call does. A client-only extension stays
compatible before the first extensions_loaded, with no session half at
all.
Measured in the prototype on macOS arm64, on a session of 1,047 tool calls
(research/tui-prototype/SEAMS.md): a
Lua ledger row costs about 8 µs to draw, more than half of it crossing between
Rust and Lua. With the cache, scrolling took 0.63% of a core against 0.59% for
built-in rows, and Lua ran zero times while scrolling or searching. Without
it, every rebuild of the conversation would call Lua for every row. The timings
do not carry over to Linux; the call counts do.
Input and focus
Not built yet (focused-slot keys and focus): see #2720.
One slot has focus at a time: the input box, an open view, or the overlay on
top. An extension's view or overlay takes focus when it opens.
Keys reach the focused slot's on_key first, as names such as
ctrl+o, alt+up or shift+enter, and typed text as text. Typed text is
what bare typing names below. A paste is one event holding the whole pasted
text before the built-in box collapses it, so a replaced box sees the raw
text (docs/extensions.md, "Commands and screens"). The handler
returns whether it handled the key. A key it did not handle goes to the key
map as if no extension were there.
Whole-screen bindings act before the built-in key map. An eligible
run binding runs before every built-in early path; an action binding
runs before them where the Bindings table lists it for the context on
screen ("Bindings"). Neither kind acts with no session on screen, on a
job's live PTY view, or for a key the person set in keys. A run
binding never acts while an overlay, a picker or search has the keyboard,
and bare typing never reaches it in the input box: a single character
with no modifier but Shift, the space bar, and shift+space type instead.
A handled run settles with nothing built in running; drained notices
settle before the fallthrough, and action events keep their built-in
settle behavior. Only Ctrl+C reaches the bindings from the /keys
screen, so no screen code skips dispatch: Ctrl+C itself is unregistrable.
Esc closes whatever is on top, or interrupts the turn, unless the
focused slot handles it itself.
The second Ctrl+C always quits ("Quit"), whatever the focused
slot does, so a slot that swallows every key cannot trap the person. The
first Ctrl+C is the slot's, even with the box empty; unhandled, it clears
the draft or arms the quit prompt as built in. The terminal counts the
presses itself: a Ctrl+C within about a second of an earlier one quits,
whether or not the slot handled the earlier one. The second Ctrl+C is the
only key the terminal keeps from the focused slot.
A click on a span with a click id goes to that slot's click handler,
with the id and the session on screen.
The wheel, a drag and any click it does not handle go to the terminal, so
scrolling and selection keep working.
A key that needs the kitty keyboard protocol, such as shift+enter, works
once keyboard detection finishes ("Keys", "Rules"). An extension that binds
one also binds a key that works without the protocol, as the built-ins do.
Every click target an extension draws is a focus stop in navigate mode
("Moving through the conversation"), so its widgets need no focus order of
their own. The terminal finds them in the cached spans, whose click ids are
part of the renderer's output, so the cache key needs nothing more and finding
them calls no Lua. Enter on a focused stop makes the same click call.
A key or click handler runs only when input arrives, so it adds nothing while
nothing happens ("Performance"). Its declared timeout bounds it. The frame
budgets in docs/performance.md are measured without a TUI extension, and a
handler's time is the extension author's cost, as its timers are
("Animation").
Animation
A renderer may declare animate = { interval_ms }. For every animated slot — conversation items, notices and chrome — the terminal calls it again when the frame advances, with frame in its input. An animated call's input also carries now, the time of the frame in Unix milliseconds, so a renderer can draw elapsed time or a countdown. The terminal uses one timer for all motion. It asks for a timer only
while an animated item or notice row was painted in the previous frame.
Intervals below 120 ms use that floor instead.
The terminal calls an item when at least one of its rows was painted in the
previous frame. It may make one due call on the frame the item scrolls off.
After that unpainted frame, it makes no further calls until the item is painted
again. A swapped view that hides the conversation counts as an unpainted
frame; the item resumes at its stored frame when the conversation returns.
Frame 0 is the still form. Under reduced motion, the terminal draws frame 0
once and makes no animation calls. When reduced motion ends, the next paint
resumes at frame 1. A renderer that returns animate = false stays stopped
until its input changes. A renderer that declares no animate gets no now:
it draws from timestamps alone, and its input changes only when the events
do. A width change redraws a stopped item once at its
stored frame, then uses the cached lines for that width. A dropped page starts
again at frame 0. Closed draws such as search and counts do not advance or
schedule animation. They use stored lines when available; on a miss, they may
cache frame 0 without changing animation state.
A notice animates as a conversation item does: frame 0 is still, and later
frames advance only while a replacement row was painted in the prior frame. An
advanced open frame's one result both measures and draws. After fade or
dismissal, a re-raised notice is new and starts at frame 0; its animation
state goes when the notice does. Live notices with identical code and text
have independent frames. The animation key is stable across page changes;
a new per-Screen cache starts a live notice at frame 0. A replacement
returning no lines stays hidden until it fades or is pruned, and never advances
or schedules animation while hidden. An event notice's fade and a condition's
re-evaluation are unchanged, so an animation never holds a notice on screen.
An extension's own timers (host.after, host.every) are for work other than
drawing. They wake the terminal whether or not anything is on screen, which is
the extension author's cost to keep down.
A renderer that errors or returns the wrong shape keeps its built-in fallback
with no further calls until its input changes ("When an extension fails"),
and a timeout switches the extension off as a still one does.
When an extension fails
An error or a wrong shape falls back to the built-in for that item. The
failure is cached against the item's input, so the renderer is not called
again until that input changes. One notice names the extension, the slot
and the Lua error, once for each extension and slot until /reload. A key or click handler that errors
counts as not having handled the input. An extension's own view or overlay
has no built-in, so it closes. A key handler that errors or returns the
wrong shape likewise counts as not handled, falling back to the built-in
key map with one hook_failed notice for each extension and key slot
until /reload; a TUI command's run that errors or returns the wrong
shape likewise counts as not handled, with one hook_failed notice for
each extension and command until /reload (true, false and nil
returns are ignored); a key or command handler that passes its timeout
switches the extension off until /reload, with one extension_failed
notice, as a still renderer does. A focus handler that errors or returns
the wrong shape counts as not having handled the input, with one
hook_failed notice for each extension until /reload; a focus handler
that passes its timeout switches the extension off until /reload, with
one extension_failed notice.
Not built yet (focused-slot key handlers): see #2720.
A timeout switches the extension off in this terminal until /reload
(the terminal command; the reload driver command acts on the session
only), with one notice. Every slot it replaced
goes back to its built-in, so one freeze of the declared length is the most
it can cost.
Not built yet (replaced input box): see #688.
A replaced input box that fails hands over to the built-in box with the
draft intact, because the terminal holds the draft.
When two extensions want one slot
Panel cards, views, overlays and slash commands are keyed by the extension's
name, so they stack. A slot that holds one thing conflicts: a ledger row for
one tool, the input box, the layout, or one key.
Two extensions replace the same slot: neither gets it. The built-in
stays, and a notice names both. tui.slots."<slot>" names the one that
wins (docs/configuration.md). Two extensions binding the same key follow
the same rule, as tui.slots."key:<key>". This is the rule for commands
(docs/extensions.md, "Commands and screens").
The notice comes once for each slot and set of contenders until /reload. A tui.slots."<slot>" that names none of them picks no winner, and the notice names the setting.
A key the person bound in keys is the person's. An extension that
binds the same key does not get it, and a notice names the extension. The
registration stays dormant and reactivates at once when the person binding
lifts, so a /keys change flips the owner per stroke. A key the person
owns stays theirs in every context, even where the action does not act.
Whole-screen keys canonicalize before they contend, with the same grammar
as keys ("Bindings"): modifier order and the case of modifier and key
names never distinguish two spellings, while an uppercase letter reads as
Shift with that letter, so Ctrl+C parses as ctrl+shift+c and stays
bindable, and plain ctrl+c never binds. The first registration to
canonicalize to a key wins; a later one is skipped with one notice naming
the extension. A key with one contender and no setting still selects that
contender. An unparseable key suffix, or a setting naming no registered
contender, selects no winner, with one notice naming the full setting, for
example:
Invalid key binding setting: tui.slots."key:ctrl+"; the key does not parse; no extension wins.
A setting that names an extension that does not contend for the key never
silently falls back to the one that does.
A per-tool ledger row beats the catch-allledger_row, with no notice.
An extension replacing a built-in is not a conflict. The extension wins,
as it does for a tool it registers by name.
Performance
The terminal holds the budgets in docs/performance.md: its idle memory, idle
CPU and time to first frame. The design keeps to them this way:
Nothing runs while nothing happens. With no turn, delegate or job running, no animated item or notice on screen and no counting "cache resets in" row on screen, there is no timer: no frame, no byte written (an on-screen animated item or notice holds the timer, "Animation"). A counting "cache resets in" row sets one wake, separate from the animation timer, for the moment its text next changes: once a minute, once a second in its last minute, and none once it reads "expired" or leaves the screen. A still pointer sends nothing under hover.
The first frame waits only for the session's last page and TUI extensions. Keyboard detection, the logo image and session listing arrive later. The first-frame budget was measured without a TUI extension. Before the first frame, attaching reads the last page with history; afterward, it reads the whole log once ("History and paging"). The slow-class fold ceiling is 138 ms per MiB (docs/performance.md). Run 40909518207 measured 56.7 ms per MiB for a 1 MiB log and 43.1 ms per MiB for a 10 MiB log on Linux x86_64. The 15 ms per MiB target remains outside the gate. Follow-up #3652 tracks reducing the cost to that target. On macOS arm64, the pass takes about 12 ms per MiB, so a large session's scroll bar appears later than a small one's.
Memory follows the window, not the session, because history is paged.
A frame redraws only the rows that changed.
Each frame is written inside synchronized output, mode 2026. The first frame and frames drawn on resize are included; a terminal without support ignores the sequences.
Wide variation-selector cells
A cell holding a variation selector (for example ⚠️) that measures two columns is written with its trailing cell first, then the cell itself. ratatui-crossterm moves the cursor whenever a cell is not at the last column plus one on the same row, so the reordered pair still moves before each cell and draws the frame on terminals giving the emoji one cell and on those giving it two alike. Cells that are not such a pair keep their order.
Configuration
The terminal reads these keys (docs/configuration.md, "Keys"):
Key
What it sets
tui.rail.shown
Whether the rail shows; on by default ("The rail")
tui.rail.width
The rail's share of the screen's width
tui.panel.width
The panel's share of the screen's width
tui.panel.cards
Which cards the panel shows, and their order
tui.theme
The theme; unset, it follows the terminal's appearance
tui.reduced_motion
Reduced motion
Not built yet: see #1506.
Key
What it sets
tui.attention.notification
The OSC 9 desktop notification
tui.attention.bell
The bell
tui.attention.title
The state in the terminal title
tui.hover
Hover, and mode 1003
tui.inline_images
Inline images
tui.logo_glyph
⌇ or ≈ in the logo
tui.slots."<slot>"
Which extension fills a slot or key two extensions want ("When two extensions want one slot")
The skills view writes skills.disabled. The tools view writes an MCP
server's or an extension's tools.enabled and tools.disabled.
Evidence
research/tui-surface/: the four toolkits
probed. ratatui with crossterm is the only one with zero idle wakeups, at
1.9 MiB peak footprint on macOS arm64, against 11 to 89 MiB for Bubble Tea,
OpenTUI and Textual.
research/tui-prototype/README.md: a
throwaway ratatui program that replays a fixture session in a real terminal.
It measures the glimmer's and hover's cost, keyboard detection, and holds
the prototype's key map.
research/tui-prototype/SEAMS.md: a
Lua renderer for one tool's ledger row, its cost with and without the cache,
and the span shape that kept selection, copy and search working.
research/tui-prototype/README.md,
"The rail (#692)": the rail's prototype. The owner compared a list, cards
and tabs, then card heights, in Ghostty, and chose the cards above (#692).