Settings

The config file

flockr reads ~/.config/flockr/config.toml. Set FLOCKR_CONFIG_PATH to use a different file. flockr --help prints the path in use.

The file is TOML. You only need the keys you want to change; everything else uses its default. A file that doesn't exist means all defaults.

[theme]
name = "tokyo-night"

[ui]
sidebar_position = "right"
seen_delay_ms = 1500

See every option

Print the full default config, with a comment for each key:

flockr --default-config

Every key in it is commented out. If you don't have a config file yet, save it as a starting point and uncomment what you need:

flockr --default-config > ~/.config/flockr/config.toml

The same keys are listed in the Configuration reference.

The settings screen

Press prefix+s to open settings. Changes save to config.toml and apply at once. The screen has six sections:

Section	Covers
Appearance	Theme, light/dark switching, status indicators, working pulse, pane borders, outer borders, pane gaps, scrollbars, agent names on borders, tab bar position, and hiding a single tab
Sidebar	Position, collapsed mode, start collapsed, section headers, header counts, divider, buttons, grabbed-space style, and spacing and borders for spaces and agents
Alerts	Pop-up delivery, position, and delay; sound; the copy notice; done badge delay and scope
Behavior	Mouse capture, copy on select, wheel scroll lines, close confirmation, naming new tabs and spaces, new pane folder, and keeping agents in use first
Session	Resume agents on restore and saving pane history
Integrations	Agent integrations and their status

If the config file has errors, the settings screen says so and shows defaults.

Reload after editing

After you edit config.toml by hand, reload it in the running server:

Press prefix+shift+r, or
run flockr server reload-config.

Some keys need a full server restart instead. The reference notes these, for example server.allow_unelevated_clients and every key in [mobile], [flock], and [web] (except flock.approve_messages). ui.sidebar_start_collapsed takes effect on the next launch.

Check for errors

flockr config check

It prints config: ok, or config: issues found followed by each problem. It exits with status 1 when it finds issues.

Reset keybindings

flockr config reset-keys

This copies config.toml to a backup in the same directory (config.toml.bak-keybind-v2-<timestamp>), then removes [keys], [keys.indexed], and [[keys.command]] (your custom commands too). It prints the backup path and the command to restore it. Run flockr server reload-config to apply the default keys in a running server.

Environment variables

Variable	Meaning
`FLOCKR_CONFIG_PATH`	Use this config file instead of `~/.config/flockr/config.toml`.
`FLOCKR_INSTALL_DIR`	Install directory for the install scripts.
`FLOCKR_LOG`	Log filter for the log files. Default `flockr=info`.

flockr sets these in every pane it runs:

Variable	Meaning
`FLOCKR_ENV`	`1` inside a flockr pane.
`FLOCKR_WORKSPACE_ID`, `FLOCKR_TAB_ID`, `FLOCKR_PANE_ID`	IDs of the space, tab, and pane.
`FLOCKR_SOCKET_PATH`	The session's API socket.
`FLOCKR_BIN_PATH`	Path of the flockr binary.