Presentation tokens
TL;DR: Tokens format Fut’s tab bar and workspace list using values Fut already knows. They never run commands. Use this page as the context-specific token catalog and Configuration for layout syntax.
Presentation tokens are pure, typed values expanded from the resource snapshot and client state already held by Fut. They never execute commands or perform I/O. Tokens are valid only in the documented context; a misspelling or out-of-scope token prevents the interactive client from starting.
A token segment is explicit TOML:
{ token = "tab.name", prefix = " ", suffix = " ", max_width = 24, style = "current", inverted = true, pill = true }
If the token is empty, its prefix, suffix, and pill caps are also omitted.
inverted = true turns the configured semantic foreground into a filled
background using terminal reverse-video, preserving theme-adaptive glyph
contrast and other composed modifiers. pill = true surrounds that inverted
content with pill_left and pill_right under the Nerd Font preset; when the
caps are empty under the Unicode or ASCII preset, only the inverted content is
rendered.
Tab-bar tokens
These may appear in groups under ui.tab_bar.left, center, or right.
| Token | Value |
|---|---|
fut |
fut when the tab bar is passive; empty while it is keyboard-active |
session.name |
Current session name |
workspace.name |
Current workspace name; unnamed workspaces present their live location |
workspace.icon |
Workspace icon from the selected preset |
tab.name |
Current tab name |
tab.index |
One-based current tab index |
tab.pane_count |
Number of panes in the current tab |
client.zoom |
Configured zoom icon while zoomed; otherwise empty |
client.help |
Contextual create/rename/close help while the tab bar is keyboard-active |
client.waiting |
Configured ui.icons.notification and this client’s count of unread agent notifications and terminal bells across Fut; empty when zero |
session.waiting |
Configured ui.icons.notification and this client’s count of unread agent notifications and terminal bells in the current session; empty when zero |
The special { component = "tabs" } segment renders the focus-aware repeated tab collection. At most one may occur in a tab bar.
Tab-item tokens
These may appear only under ui.tab_bar.item.segments.
| Token | Value |
|---|---|
tab.marker |
Current icon for the active tab, otherwise its one-based index |
tab.index |
One-based tab index |
tab.name |
Tab name |
tab.id |
Compact, reversible stable tab ID |
tab.closing |
Closing icon while closing; otherwise empty |
tab.pane_count |
Number of panes in the tab |
tab.icon |
Tab icon from the selected preset |
tab.activity |
Rolled-up agent/terminal attention: spinner for working, ! for blocked or BEL, or • for completion; empty when inactive |
Current, closing, and keyboard-selected styles are composed over every item segment.
Workspace-row tokens
These may appear in the row.left, body, right, or detail fields of a component = "workspaces" entry under either ui.sidebar.left.components or ui.sidebar.right.components.
| Token | Value |
|---|---|
workspace.index |
One-based workspace index |
workspace.name |
Workspace name; unnamed workspaces present their live location, or multiple when panes disagree |
workspace.id |
Compact, reversible stable workspace ID |
workspace.root |
Live workspace location: the Git work tree (or directory) every open pane is inside, observed from pane working directories with the creation-time root as fallback; multiple when panes disagree |
workspace.root_name |
Final component of the live workspace location; multiple when panes disagree |
workspace.closing |
Closing icon while closing; otherwise empty |
workspace.tab_count |
Number of tabs in the workspace |
workspace.icon |
Workspace icon from the selected preset |
workspace.activity |
Rolled-up agent/terminal attention: spinner for working, ! for blocked or BEL, or • for completion; empty when inactive |
workspace.git_branch |
Current branch at the live workspace location; multiple when panes disagree, empty outside a Git work tree or until resolved |
workspace.git_added |
+N inserted lines against HEAD, styled added; empty when none |
workspace.git_deleted |
-N deleted lines against HEAD, styled deleted; empty when none |
Current, closing, and keyboard-selected styles compose over each workspace row.
The daemon resolves Git tokens with bounded background git processes and refreshes each workspace at most every five seconds. Each Git command has a two-second timeout. Branch, insertion, and deletion values enter the authoritative resource snapshot together in at most one revision and only when changed, so every attached client sees the same status. They never block rendering and all three stay empty for non-Git roots, errors, timeouts, or a repository that disappears.
Sidebar header and footer tokens
These may appear in the header and footer fields of a component = "workspaces" entry under either sidebar side:
| Token | Value |
|---|---|
fut |
fut |
session.name |
Current session name |
workspace.name |
Current workspace name; unnamed workspaces present their live location |
workspace.icon |
Workspace icon from the selected preset |
sidebar.display |
Current display label: expanded or minimized |
sidebar.visibility |
Current compact visibility label: visible, automatic, or hidden |
sidebar.status |
Current display and visibility plus contextual controls, switching progress, or a retryable error |
Extension tokens
Explicit local extensions may declare namespaced string tokens in their manifests and publish materialized values through fut token publish. The qualified UI name is <scope>.extension.<extension-id>.<name>, such as workspace.extension.review-status.state. Fut validates configured references against the explicit extension catalog on client startup and every configuration reload; undeclared or out-of-context names reject the complete new configuration.
Compatibility follows the resource represented by each format:
- Generic current tab-bar groups and workspace-sidebar headers and footers accept declared session, workspace, tab, and pane tokens from the focused resource’s current ancestry.
- Tab-item segments accept only declared tab tokens and resolve them from that item.
- Workspace-row segments accept only declared workspace tokens and resolve them from that row.
A declared value that has not been published is empty, including its configured prefix and suffix. Published values are plain text and receive only the normal group, segment, and item styles already configured by the user; a value cannot inject a style. A manifest may opt one token into presentation = "spinner"; any non-empty value then renders as the client’s configured animated spinner in generic tab-bar groups, tab items, sidebar headers/footers, and workspace rows. presentation = "pulse" keeps the text while breathing it over two seconds; presentation = "wave" moves a faint band across its characters. Both text effects include the configured prefix and suffix without changing glyph weight; pill caps retain a stable fill. The client animation clock supplies frames without extension I/O or repeated token publication. Values are shared by every client and removed with their target.
A non-empty publication may also attach one action: --action-pane-id navigates the client that clicks the token, while --action-command runs one of the publishing extension’s declared commands. The whole visible token segment is clickable, including its prefix, suffix, and pill caps. Token hits take precedence over ordinary tab or workspace-row navigation in the tab bar and expanded workspace sidebar. Command actions use the clicked token resource as their extension context, so a command on another workspace’s row receives that workspace’s root, IDs, and extension configuration rather than the clicking client’s previously focused workspace.
The daemon accepts a pane action only when the pane is a live descendant of the publication target, and a command action only when that command belongs to the publishing extension. An empty value cannot carry an action. If an action’s pane disappears after publication, clicking fails safely with a concise client error. Rendering itself never invokes an extension or performs publication I/O; actions run only after an explicit click.
See Extensions for declarations, publication syntax, limits, and the security boundary.