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+Efrom the session list. The name is the Task'sthurbox.dev/namelabel. - 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 withCtrl+C, paste withCtrl+V. With no selection,Ctrl+Csends 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+Kmove the selected session (and its nested children) down/up, andShift+Ssorts sessions by name within each repo group. A status change only recolors the dot, never moves a row, and the order survives restarts. -
Ctrl+Qquits and leaves every session running.Ctrl+Ddeletes the session's Task (fleet delete task): Fleet stops the agent and removes its worktree, keeping its branch, and its uncommitted work underrefs/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+Knavigation 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.
[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 attachandfleet shellname, 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 doctorchecks each listed Fleet and says which one cannot be reached. Every key is in Configuration.
Global Search #
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;
Escputs back exactly what you were looking at. -
Metadata matching is subsequence (typing
oc52findsfix-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 ofsettings.toml( see Configuration ): opt into the timing-onlyBusy → Waitingedge 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+Ccopies);Ctrl+Clickopens 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.
[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.