Every key in ~/.config/flockr/config.toml, by section, with its default. The source is flockr --default-config, which prints the same keys with full comments. Keybindings are listed in the Key reference.
Reload a running server with flockr server reload-config or prefix+shift+r after editing. Keys marked "restart" need a server restart instead.
Top level
| Key | Default | Meaning |
|---|
onboarding | true | Show the first-run screen on startup. A missing key also shows it; set false once you've seen it. |
[theme]
| Key | Default | Meaning |
|---|
name | "catppuccin" | Theme. See Themes for the list. |
auto_switch | false | Follow the host terminal's light or dark appearance. |
dark_name | "catppuccin" | Theme for dark appearance when auto_switch is on. |
light_name | "catppuccin-latte" | Theme for light appearance when auto_switch is on. |
[theme.custom] overrides single color tokens. [theme.custom.light] and [theme.custom.dark] add overrides per appearance. Colors accept #rrggbb, named colors, rgb(r,g,b), or "reset".
[terminal]
| Key | Default | Meaning |
|---|
default_shell | "" | Executable for new interactive panes. Empty means $SHELL, then /bin/sh. |
shell_mode | "auto" | "auto", "login", or "non_login". "auto" uses login shells on macOS. |
new_cwd | "follow" | Directory for new panes, tabs, and spaces: "follow", "home", "current", or a fixed path. |
kitty_graphics | true | Render pane images in Kitty graphics-compatible outer terminals. |
[keys]
The prefix key and every action binding. See the Key reference and Keybindings. Sub-tables: [[keys.command]] for custom commands and the legacy [keys.indexed].
[server]
| Key | Default | Meaning |
|---|
allow_unelevated_clients | false | Windows only: allow ordinary same-account clients to control an elevated server. Restart. |
headless_cols | 120 | Width of the virtual terminal when no client is attached. |
headless_rows | 40 | Height of the virtual terminal when no client is attached. |
Attached clients always use their own terminal size.
[worktrees]
| Key | Default | Meaning |
|---|
directory | "~/.flockr/worktrees" | Where new Git worktrees go. |
[ui]
| Key | Default | Meaning |
|---|
sidebar_width | 26 | Default sidebar width; scaled based on space names. |
sidebar_min_width | 18 | Minimum width when expanded, in columns. |
sidebar_max_width | 36 | Maximum width when expanded, in columns. |
sidebar_start_collapsed | false | Start collapsed. Takes effect on the next launch. |
sidebar_collapsed_mode | "compact" | "compact" keeps a narrow status rail; "hidden" uses zero width. |
sidebar_position | "left" | Screen edge: "left" or "right". |
mobile_width_threshold | 64 | Terminal width at or below which flockr uses the single-column mobile layout. |
| Key | Default | Meaning |
|---|
mouse_capture | true | Capture the mouse for flockr's UI. false lets the terminal handle normal clicks, such as Cmd-clicking URLs. |
copy_on_select | true | Copy mouse selections at once. false keeps the selection until ctrl+c (or Cmd+C when the host forwards it). |
host_cursor | "auto" | "auto", "native", or "drawn". "auto" draws flockr's own cursor on native Windows and WSL and uses the terminal cursor elsewhere. |
right_click_passthrough_modifier | "" | Modifier that sends right-click hold and drag to pane apps instead of opening flockr's pane menu. Empty disables it. Shift is not supported. |
pane_focus_passthrough | [] | Foreground programs that get direct pane-focus keys first, such as ["nvim"]. See nvim and pane focus. |
redraw_on_focus_gained | true | Full redraw when the outer terminal regains focus. false reduces flashing. |
mouse_scroll_lines | 3 | Scrollback lines per mouse wheel notch. |
Agents and seen state
| Key | Default | Meaning |
|---|
seen_delay_ms | 0 | Milliseconds a finished agent must stay on screen before its done badge clears. 0 clears at once. |
seen_scope | "pane" | What counts as seen: "pane" (focused pane only) or "tab" (every pane in the tab). |
keep_agents_in_use_first | false | Move a pane whose agent starts a fresh session behind the agents in use. Needs integrations. |
show_agent_labels_on_pane_borders | false | Show agent labels in split pane borders when no pane name is set. |
status_indicators | "dots" | "dots" or "symbols" (distinct glyphs per state). |
pulse_working | true | Pulse the working indicator. |
Prompts and confirmations
| Key | Default | Meaning |
|---|
confirm_close | true | Ask before closing a space. |
prompt_new_tab_name | true | Ask for a name for each new tab. |
prompt_new_workspace_name | false | Ask for a name for each new space. |
Panes
| Key | Default | Meaning |
|---|
pane_borders | "auto" | "auto" (split panes only), "always" (a lone pane too, with outer borders on), or "off". true/false still parse. |
pane_outer_borders | true | Borders along the outside edge of the pane area. |
pane_scrollbars | true | Interactive scrollbars beside panes. |
pane_gaps | true | Keep split panes visually separated instead of sharing borders. |
main_pane_width | 80 | Main pane width in main_vertical layouts: cells or a percentage. |
main_pane_height | 24 | Main pane height in main_horizontal layouts: cells or a percentage. |
Tab bar, title, and accent
| Key | Default | Meaning |
|---|
hide_tab_bar_when_single_tab | false | Hide the tab row when a space has one tab. |
tab_bar_position | "top" | "top" or "bottom". |
tab_bar_right | [] | Status entries at the right of the tab bar. Types: zoom, hostname, datetime, text, and command. |
tab_bar_right_separator | " " | Text between right-side entries. |
window_title | "{hostname}: {workspace}" | Title flockr writes to the outer terminal. Tokens: {hostname}, {workspace}, {tab}, {pane}, {terminal_title}. "" leaves the title alone. |
accent | "cyan" | Accent color for highlights, borders, and navigation UI. |
| Key | Default | Meaning |
|---|
header | "band" | Section headers: "band" or "plain". |
header_counts | true | Show counts next to headers. |
divider | "handle" | "handle", "line", or "dim". |
buttons | "chip" | "chip" or "text". |
grab | "marker" | Grabbed space in navigate mode: "marker" or "fill". |
| Key | Default | Meaning |
|---|
row_gap | 0 | Blank rows between agent entries. |
border | "none" | Where each space's agents end: "none", "underline", or "bracket". |
rows | [["state_icon", "number", "machine", "workspace", "tab"], ["agent"]] | Tokens per row. See The sidebar. |
[ui.sidebar.agents.rows_by_agent] sets rows per canonical agent ID, for example claude = [...].
| Key | Default | Meaning |
|---|
row_gap | 0 | Blank rows between space entries. |
border | "none" | Where each space ends: "none", "underline", or "bracket". |
rows | [["state_icon", "number", "workspace"], ["branch", "git_status", "diff_stat"]] | Tokens per row. |
[ui.toast]
| Key | Default | Meaning |
|---|
delivery | "off" | Background pop-ups: "off", "flockr" (in-app), "terminal" (outer terminal), or "system" (OS notification service). |
delay_seconds | 1 | Seconds to wait before a pop-up, so quick changes don't show one. |
flockr.position | "bottom-right" | In-app toast position ([ui.toast.flockr]). |
clipboard.enabled | true | Show a short notice when text is copied ([ui.toast.clipboard]). |
clipboard.position | "bottom-center" | Position of the copy notice. |
[ui.sound]
| Key | Default | Meaning |
|---|
enabled | true | Play sounds when agents change state in background spaces. |
path | (unset) | One mp3 file for all sounds. Relative to the config file's directory. |
done_path | (unset) | mp3 for finished notifications only. |
request_path | (unset) | mp3 for needs-attention notifications only. |
[ui.sound.agents] sets "default", "on", or "off" per agent. droid is muted by default.
[session]
| Key | Default | Meaning |
|---|
resume_agents_on_restore | true | Resume supported agents into their own sessions after a server restart. Needs integrations that report sessions. |
startup_per_agent_delay_ms | 100 | Milliseconds between agent restores. 0 starts them without spacing. |
[remote]
| Key | Default | Meaning |
|---|
manage_ssh_config | true | Run flockr --remote SSH through a generated config that includes your ~/.ssh/config and adds keepalive fallbacks. false runs plain SSH. See Remote machines. |
[experimental]
| Key | Default | Meaning |
|---|
allow_nested | false | Allow launching flockr from inside a flockr pane. |
pane_history | false | Save recent pane screen history across full server restarts. |
switch_ascii_input_source_in_prefix | false | Switch the input source to ASCII while prefix mode is active, so prefix keys work with an IME. macOS and Windows only. |
reveal_hidden_cursor_for_cjk_ime | false | Expose the focused pane's cursor to the outer terminal so macOS input methods track the candidate window. |
cjk_ime_agents | [] | Only reveal the cursor for these detected agents. Empty means any focused pane. |
cjk_ime_cursor_shape | "steady_block" | block, steady_block, underline, steady_underline, bar, or steady_bar. |
[advanced]
| Key | Default | Meaning |
|---|
scrollback_limit_bytes | 10000000 | Maximum scrollback kept per pane, in bytes. |
[mobile]
Coming in 1.2.0. These keys are not in the current release (1.1.0).
The gateway for the flockr phone app. Off by default. All keys need a server restart. See Pairing a phone.
| Key | Default | Meaning |
|---|
enabled | false | Start the gateway. |
listen | [] | Literal IP addresses to bind, optionally with a port. 0.0.0.0 and :: are rejected. |
port | 47390 | Port for listen entries without one. |
advertise | [] | Hosts shown in the pairing QR, in try order. Empty means the listen addresses. |
name | "" | Name shown in the app and in push notifications. Default: host name. |
max_devices | 8 | Paired device limit. |
pairing_ttl_secs | 600 | Pairing code lifetime in seconds (60 to 3600). |
[mobile.push]
See Push alerts.
| Key | Default | Meaning |
|---|
enabled | true | Send push notifications when an agent becomes blocked or done. |
blocked | true | Push on blocked. |
done | true | Push on done. |
confirm_delay_ms | 5000 | Re-check delay before sending, to drop alerts for status flicker (0 to 60000). |
expo_access_token | "" | Optional Expo access token, sent as a Bearer token. |
[flock]
Coming in 1.2.0. These keys are not in the current release (1.1.0).
Join this machine's server to a flock. Off by default. All keys need a server restart, except approve_messages. See Flock setup.
| Key | Default | Meaning |
|---|
enabled | false | Join a flock. |
listen | [] | Literal IP addresses to bind (only the hub needs this). 0.0.0.0 and :: are rejected. |
port | 47392 | Port for listen entries without one. |
name | "" | This machine's name in the flock. Default: host name. |
approve_messages | "other-projects" | Which agent messages wait for a person: "other-projects", "never", or "always". See Agent messages. |
[web]
Coming in 1.2.0. These keys are not in the current release (1.1.0).
Serve the flockr web app over plain HTTP. Off by default. All keys need a server restart. See Web app.
| Key | Default | Meaning |
|---|
enabled | false | Serve the web app. Needs the [mobile] gateway too. |
listen | [] | Literal IP addresses to bind. 0.0.0.0 and :: are rejected. |
port | 47393 | Port. |
dir | "" | Path to the built web app's dist folder. |
[update]
Not printed by --default-config. flockr channel set writes channel here ("stable" or "preview"). flockr does not self-update, so it has no effect on getting new versions. See Updating.