thurbox features

What the interface adds on top of Fleet. For what runs the sessions, see Fleet features.

A customizable interface #

There is no interface compiled into the binary. thurbox boots a kernel, reads a directory, and draws whatever Lua it finds there — so every pane, the session list included, is a file you can move, turn off, delete, rewrite, or install from someone else. You do not have to write any of it yourself: ask the agent you already have running. The full tour is The Interface.

Where each surface lives #

Surface Kind Where it lives
Session list bundled 10_sessions.lua
Agent terminal bundled 20_agent.lua
Global search bundled 65_search.lua
Session creation bundled 70_new_session.lua (a float)
The arrangement bundled ui/layout.lua
Themes · settings · help kernel chrome Ctrl+Y · Ctrl+, · F1
Code review installable thurbox-code-review
Info panel installable thurbox-info-panel
CPU / RAM gauges installable thurbox-cli plugin install top
Panes anyone else wrote installable ui/plugins.toml

Bundled means it ships with thurbox and is yours to edit, move or delete — the arrangement included. Installable ones sit in plugins.toml on exactly the same terms: the review pane claims its chord by itself, and the info panel wants one layout.lua line.

The session list #

Heads up: what the session list can show depends on the signals each agent CLI exposes.

Every session of every Fleet thurbox follows, in one list, with the agent's live terminal beside it. Each session is a Fleet Task (Sessions as Tasks), so quitting thurbox leaves it running.

  • Create a session with Ctrl+N : Fleet → place → repository → name and branch → agent. The Fleet step is skipped when only one Fleet is listed. The places and agents offered are the chosen Fleet's, and the agent step is skipped when that Fleet offers one harness. Alt+W gives a repository a worktree of its own.
  • Rename a session with Ctrl+E from the session list. The name is the Task's thurbox.dev/name label.
  • Each row shows the agent's live activity when the CLI reports one (via its terminal title), next to a colored status dot.
  • Open URLs in terminal output with Ctrl+Click. Select text with a mouse drag, copy with Ctrl+C, paste with Ctrl+V. With no selection, Ctrl+C sends SIGINT to the active session.
  • Toggle a shell pane beside the agent with Ctrl+T.
  • Reorder the list by hand: with the session list focused, Shift+J / Shift+K move the selected session (and its nested children) down/up, and Shift+S sorts sessions by name within each repo group. A status change only recolors the dot, never moves a row, and the order survives restarts.
  • Ctrl+Q quits and leaves every session running. Ctrl+D deletes the session's Task (fleet delete task): Fleet stops the agent and removes its worktree, keeping its branch, and its uncommitted work under refs/fleet/preserved/ for 30 days. There is no undo.

Parent Sessions (Lead / Worker) #

A Task can name a parent with its gateway.fleet.dev/parent label, so a lead session that spawns workers shows them under it.

  • In the session list, children nest under their parent within the same repo group. Ctrl+J / Ctrl+K navigation walks the tree exactly as rendered.
  • The link is informational only — deleting a lead never deletes its workers. A dangling parent renders the child as a top-level session again.

Several Fleets #

thurbox can follow several Fleets. List them in ~/.config/thurbox/settings.toml. With no [fleets] table, thurbox uses one Fleet on this machine. Once the file lists a Fleet, thurbox uses only the listed Fleets.

~/.config/thurbox/settings.toml
[fleets.laptop]
transport = "local"                     # the default

[fleets.box]
transport = { ssh = "me@box" }
program = "/home/me/.local/bin/fleet"   # ssh does not read your login PATH

[fleets.ubuntu]
transport = { wsl = "Ubuntu" }
  • A row shows its Fleet, and its place when the place is not local. A Fleet that cannot be reached keeps its rows, marked unreachable.
  • Each command for a session goes to that session's own Fleet. A new session goes to the Fleet picked in the new-session flow, which browses that Fleet's folders and branches, on whichever machine it runs.
  • The agent's pane and its companion shell are the streams fleet attach and fleet shell name, over the link to the session's Fleet.
  • thurbox never starts, restarts or sets up fleet up: run it as a service (Keep fleet up running). While none runs, the status line names the command that starts it.
  • thurbox-cli doctor checks each listed Fleet and says which one cannot be reached. Every key is in Configuration.

Press Ctrl+/ to open a non-modal search strip across the top of the interface. A result carries the pane it belongs to, so search grows a scope whenever a pane returns — sessions is the scope that has a pane today.

  • Sessions match on name, agent, worktree branch and repository and on the text on the agent's screen — the half that finds a session by the error in it.
  • Matches highlight live in the pane itself — matching rows accented, the rest dimmed — rather than being reprinted in the strip. Moving the selection previews it in the list; Esc puts back exactly what you were looking at.
  • Metadata matching is subsequence (typing oc52 finds fix-osc52 ); screen text is matched as a substring, because fuzzy matching against a whole terminal screen matches everything. A session whose metadata already matched is not scanned twice.
  • Nobody pays for it while it is closed. Reading every agent's screen every frame would be a permanent cost for a feature in occasional use, so the strip leaves its query where the kernel can see it and the screen text is served only while it is actually asking.

Responsive layout #

The arrangement adapts to the terminal size, and the thresholds are a file you can edit — ui/layout.lua , not a breakpoint compiled into the binary. It ships arranging two panes between three chrome bands:

Terminal size Arrangement
< 80 cols Centre pane only — the session column is dropped
>= 80 cols Session column (25%, min 20 cols) + centre pane
< 20 rows The header band is dropped to keep the panes usable

The centre pane is never dropped — it takes whatever the session column leaves. Everything else is yours: change a percentage, reorder the bands, or delete a line to drop one. The function only arranges , so it never calls a plugin and a mistake in it cannot break one. See the interface for how it is resolved before any plugin draws.

Themes #

Thirty-six built-in palettes (twenty-eight dark, eight light) switch live with Ctrl+Y (or F4 ) and persist across restarts.

OS Notifications #

When a session crosses into a needs-you state — the agent rang the terminal bell or emitted an OSC 9 / OSC 777 notification (usually because it is waiting on an answer or has finished a task) — Thurbox fires an OS desktop notification, so you can react without watching the TUI. The notification body is the agent's last OSC message, or Waiting for input otherwise.

  • Linux dispatches over dbus and supports click-to-focus : clicking the banner switches the TUI to that session on its next tick. macOS shows the banner but ignores clicks (the modern notification API requires a signed app bundle, which Thurbox is not).
  • It fires only while the TUI is open — the terminal parser that watches for the bell does not run headless — and is deduplicated per session, with the session you are currently viewing skipped by default.
  • Tune it in the [notifications] block of settings.toml ( see Configuration ): opt into the timing-only Busy → Waiting edge for agents that never ring a bell, toggle the sound, or change the dedup floor. Turn the whole feature off with [features] notifications = false .

Mouse Navigation #

The whole TUI is clickable (on by default; disable with the mouse feature flag below):

  • Click a row in any pane to select it and focus that pane. A plugin gets the hit for free: it returns the rects it drew, and the kernel matches the click against them.
  • Click a picker row (theme, Fleet, place, agent, branch, …) to select and confirm in one click. Open modals swallow stray clicks, so a misclick never discards typed input.
  • Hover underlines the row under the pointer; the mouse wheel scrolls the focused terminal and steps the selection while a modal is open (with a draggable scrollbar on long lists).
  • Drag selects terminal text ( Ctrl+C copies); Ctrl+Click opens a URL.

Feature Flags #

Behaviour that reaches outside the interface is switched in ~/.config/thurbox/settings.toml under [features] (seeded commented-out, so the defaults apply when absent). Every flag defaults to true — including version_check and auto_update , which reach the network, so they are the two most worth knowing you can turn off.

A pane is not switched off here. Panes are files, so turning one off is space on its row in the Interface tab — a decision recorded in plugin-state.json beside your trust grants. That is strictly more than a flag could do: it works for a plugin you wrote, which no compiled-in flag could ever have known about.

settings.toml
[features]
shell_pane = true     # Ctrl+T per-session shell
mouse = true          # mouse capture: clicks, wheel, drag-select, hover
notifications = true  # OS desktop alerts when a session needs attention
perf_hud = true       # F12 live counters
version_check = true  # GitHub update check (makes a network call)
auto_update = true    # download+verify+replace the binaries on startup (never across a major)

You don't have to hand-edit the file: press Ctrl+, (or F6 ) to open the Settings panel — a modal that views and edits all of settings.toml (the [features] toggles, the [notifications] knobs, and the scalars). Edits apply on Ctrl+S ( Esc discards); the file is also live-reloaded, so feature flags and notification knobs take effect immediately.