The sidebar

The sidebar shows your spaces and your agents, with the state of each. Click a space to switch to it, or use the keys below.

What's in the sidebar

Title row with the menu.
Spaces list: one entry per space. Worktree spaces nest under their repo.
Machines list: saved SSH machines, when you have any. See Remote machines.
Agents list: agents grouped under one header per space. A worktree's agents nest under their repo the way the spaces list shows them.

A divider separates spaces from agents. By default it has a drag grip.

All and Active

Two tabs at the top of the agents list filter it:

All: every agent.
Active: agents that are working, blocked, or done and not yet seen.

See Agent states for what each state means.

Numbering

Agents and spaces are numbered in the sidebar. The number is the key that jumps to it:

alt+1..9 focuses agent 1 to 9 (focus_agent).
alt+shift+1..9 switches to space 1 to 9 (switch_workspace).

The number row token shows these keys, so if you rebind them the sidebar follows. See Jumping between agents.

Branch and change tokens

branch on an agent row is the Git branch of the agent's own working directory. If the agent works in another checkout, such as a worktree, it shows that branch, which may differ from its space's branch.
branch on a space row is the space's branch.
git_status on a space row shows commits ahead and behind the branch's upstream, for example ↑2 ↓1.
diff_stat on a space row shows lines added and removed by uncommitted changes against HEAD, for example +12 -3. It does not count untracked files. Worktree spaces show it too.

Position, size, and collapse

Key	Default	What it does
`ui.sidebar_position`	`"left"`	Screen edge for the sidebar: `"left"` or `"right"`.
`ui.sidebar_width`	`26`	Default width. flockr scales it based on space names.
`ui.sidebar_min_width`	`18`	Minimum width when expanded, in columns.
`ui.sidebar_max_width`	`36`	Maximum width when expanded, in columns.
`ui.sidebar_start_collapsed`	`false`	Start collapsed. Takes effect on the next launch.
`ui.sidebar_collapsed_mode`	`"compact"`	`"compact"` keeps a narrow status rail; `"hidden"` uses zero width.

prefix+b collapses and expands the sidebar.

Sidebar look: [ui.sidebar]

Key	Default	Values
`header`	`"band"`	Section headers as a filled row (`"band"`) or `"plain"`.
`header_counts`	`true`	Show the number of spaces, machines, or agents next to each header.
`divider`	`"handle"`	Line between spaces and agents: `"handle"` (line with a drag grip), `"line"`, or `"dim"`.
`buttons`	`"chip"`	Clickable labels (new, menu, and the All/Active filter): `"chip"` (padded, filled) or `"text"`.
`grab`	`"marker"`	A space grabbed in navigate mode: `"marker"` (`↕` at the right edge) or `"fill"` (accent row).

Customize rows

Each space and agent entry is made of rows, and each row is a list of tokens. Set them in [ui.sidebar.spaces] and [ui.sidebar.agents].

Space rows

Tokens: state_icon, state_text, number, workspace, branch, git_status, and diff_stat.

[ui.sidebar.spaces]
rows = [["state_icon", "number", "workspace"], ["branch", "git_status", "diff_stat"]]
row_gap = 0        # blank rows between entries; 1 restores the older spacing
border = "none"    # "none", "underline", or "bracket"

Agent rows

Tokens: state_icon, state_text, number, machine, workspace, tab, pane, agent, terminal_title, terminal_title_stripped, and branch.

[ui.sidebar.agents]
rows = [["state_icon", "number", "machine", "workspace", "tab"], ["agent"]]
row_gap = 0
border = "none"

Give one kind of agent its own rows with rows_by_agent, keyed by canonical agent ID:

[ui.sidebar.agents.rows_by_agent]
claude = [["state_icon", "machine", "workspace", "tab"], ["terminal_title_stripped"], ["agent"]]

Token styles

Replace a token name with a table to style that occurrence:

[ui.sidebar.agents]
rows = [["state_icon", { token = "workspace", fg = "#89b4fa", bold = true }], ["agent"]]

fg takes #RGB or #RRGGBB. bold and dim are booleans. Fields you leave out keep their default style.

Custom tokens

Scripts and plugins can report extra values for a pane or space, and you show them with a $name token, for example $jj_status. Values come from pane metadata (flockr pane report-metadata) or workspace metadata (flockr workspace report-metadata), each with --token NAME=VALUE.

flockr workspace report-metadata w1 --source my-script --token jj_status=clean

[ui.sidebar.spaces]
rows = [["state_icon", "number", "workspace"], ["branch", "$jj_status"]]

From the settings screen

The sidebar section of the settings screen (prefix+s) covers position, collapse behavior, headers, header counts, divider, buttons, the grabbed-space style, and spacing and borders for spaces and agents. Row layouts are set in config.toml.