Using Flockdeck

Settings

Ctrl+,, or Settings at the foot of the rail, opens the settings: twelve sections in five groups on the left, and the one you are in on the right. Every control changes its setting at once, and it is the same setting the command palette and the keys change, so whichever you use, the others show it.

Window

• General: Desktop notifications. Under New panes, Auto-approve read-only in new panes: a pane opened by hand starts with this setting, and a pane started from another one (a helper started with flockdeck spawn) starts the way that pane is set. Either way the ✓ in a pane's header turns it on or off for that one pane; auto-approve read-only only ever lets through a command it is confident only reads, and never says "deny". Under Conflict radar, the switch that marks a pane whose work git predicts would conflict with another pane's; it is off until you turn it on, and Git worktrees says what it does and costs, including that a checkout git is too slow for is skipped for a while and that only the log says so. Under Hints, Show them again brings back every hint you sent away.
• Appearance: Theme: Dark, the palette this window has always drawn in; Light; or Follow system, which changes with this computer's own light-or-dark setting. Accent colour is a small fixed set of swatches, kept legible against either palette, not a free colour picker.
• Terminal: a preview at the top, then the font size (13 px unless changed, from 8 to 28), the font, how many lines each pane keeps to scroll back through (10,000 by default), and the cursor's shape and whether it blinks. The size is also Ctrl+=, Ctrl+- and Ctrl+0. Screen reader support lets a screen reader read what the agents write; it is off unless you turn it on, because it slows every terminal a little. The palette has Turn screen reader support on too.
• Keyboard: every shortcut this window's own chrome offers, grouped as Keyboard shortcuts groups them, each with a button that records the next key you press as its new binding; Reset puts one back, and Reset every shortcut to its default puts all of them back. Two actions can never share a chord: recording a chord another action has is refused, with a message naming that action, and the old binding stays until you clear or change it. This is a different thing from your terminal tool's own keybindings (Claude Code's ~/.claude/keybindings.json, say), which remaps keystrokes inside a pane; this remaps the window around it, before a pane ever sees the keystroke.

Agents

• Agents & models: the agent and model a pane starts when nobody chooses: for Every project, and for the project on screen, which can go back to Same as every project. And Claude Code's usage limits: which Claude panes read their five-hour and weekly limits for the pane header: Only where I have a status line, the default, Always or Never. It applies to a pane when it starts. Spend and limits says what each one costs. Below them, links to Routing and API keys.
• Routing: whether a helper or first prompt comes with a model chosen for the work: Off, which it is until you change it, or Automatic, for every project and for this one. Never go below keeps it off the smaller tiers. Strategy is Cost-first, quality-aware, the default, or Minimise cost: quality-aware leaves work no rule recognises exactly where it was; minimise cost routes it too, to the cheapest model the floor allows. Either way a rule that matches still decides first. Let a rule send work to another agent is off until you turn it on. The rules in force are listed, each with how often an older version's log shows it overridden where it has decided at least once, with where agents.json is, since that is where they are edited, and Clear routing history empties that log, which nothing adds to now. Agents and models has the rest.
• API keys: set, replace or clear the key each API agent uses. A key is never shown once it is set. Keys are set and cleared only at the desk: a window reached through the relay shows which are set, and no more. Below the agents, TypeSafe API key is where you paste, replace or clear the key that Let TypeSafe's Jev help read pane status needs. The field is masked and never shows the key back, only whether one is set. Saving a key sends nothing: the setting stays off until you turn it on.
• Status detection: TypeSafe API key says whether that key is set and links to API keys, where it is edited. Below it, Let TypeSafe's Jev help read pane status: whether TypeSafe's Jev model may help read the status of a pane whose agent reports none. Off by default, and it sends the last 30 lines (at most 2,000 bytes) of the pane's terminal output to a third party, with API keys, tokens, password values and secret file paths redacted. Redaction is by pattern and misses secrets with no recognisable shape. See Knowing who needs you. It is turned on only at the desk.

Connections

• Flockdeck Remote: whether paired devices are notified when an agent has been waiting, after how long (30 seconds unless changed; 15 seconds to 10 minutes), and whether the notification names the pane; then turning Flockdeck Remote on or off, the relay it goes through, this machine's name, and the paired devices. Turning it on or off, and the relay, are changed only at the desk.
• GitHub: signing in to GitHub, for pull requests, issues and CI status inside Flockdeck; see GitHub.

Account

• Account & plan: the Free plan, which is every part of the desktop app; where the relay reports one, the Flockdeck Remote plan for reaching this machine through the shared relay, a free trial and then a subscription, with the days left or the date it is paid until, paid for from Devices on a paired phone or browser; and Enterprise, coming for companies to run the relay on their own infrastructure with SSO and support.

About

• About & updates: under Version, Check for updates: whether Flockdeck looks for new releases in the background, changed only at the desk; Check for updates now asks once on the spot, whatever that switch says; and Install a specific version… to roll back or reinstall (see The command line). Then Sponsor Flockdeck, a link to GitHub Sponsors for anyone who wants to say thank you. Sponsoring buys nothing, and the app is the same either way. At its foot are the licence (PolyForm Noncommercial), the privacy policy and terms for the shared relay, and the licences.

A window reached through the relay leaves a few things to the desk: Flockdeck Remote lists them.

Type into Find a setting, at the top of the settings, to narrow the list to the sections that mention a word. In a narrow window the list and a section are two pages: pick a section to open it, and ← All settings goes back.

Elsewhere in the window

• The agent and model a pane runs: Split right (choose agent)… or New agent tab (choose agent)…. Kept with the layout.
• Which agent and model a project starts: Agents & models in the settings, or Set as default for at the foot of the picker. Kept in agents.json.
• Whether a helper's model is routed, and by which rules: Routing in the settings for the mode, the floor and the strategy; the rules themselves are edited by hand. Kept in agents.json.
• Whether Claude panes read their usage limits: Agents & models › Claude Code's usage limits in the settings. Kept in prefs.json.
• An API agent's key: API keys in the settings, API keys…, or flockdeck keys set <agent>. Kept in keys.json. At the desk only.
• Where an API agent sends its prompts: its address, in the agent picker, or flockdeck keys endpoint <agent> <url>. Kept in agents.json. At the desk only.
• A tab's name: double-click the tab, press F2 while the keyboard is on it, or Rename this tab… in the command palette. An empty name, or Use the automatic title there, goes back to the title the tab gives itself. Kept with the layout.
• Which panes the prompt bar reaches: Ctrl+Shift+B, and the ⇉ button in each pane header; Broadcast and the prompt bar has the rest. Kept until Flockdeck stops.
• The terminal's font, size, scrollback and cursor: Terminal in the settings, or the palette's entries for each. Kept in prefs.json.
• Any window shortcut: Keyboard in the settings. Kept in keybindings.json.
• A pane's auto-approve read-only, lock and recording: the ✓, padlock and record buttons in its header, or the command palette. Kept with the layout, so a pane comes back after a restart the way you left it.
• This machine's name and paired devices: Flockdeck Remote in the settings, or Flockdeck Remote…. Use Pair a device, Rename and Unpair. Kept on the relay; Flockdeck Remote has the rest.
• Notifications on paired devices: Flockdeck Remote in the settings: whether the relay tells the paired devices that asked for them when an agent has been waiting, after how long, and whether they name the pane. Kept in prefs.json; Flockdeck Remote has the rest.
• Desktop notifications: General in the settings, or Turn desktop notifications off in the palette; kept in prefs.json. The browser also asks once whether this window may show them, and keeps the answer for that run only: each run has an address of its own.
• Hints under the tab bar: their close button sends one away for good. Kept in prefs.json.
• Auto-approve read-only's own default: General › New panes in the settings. Kept in prefs.json.
• Structured agents (beta): no setting in the window. Put "structuredPanes": true in prefs.json to have them offered; Agents and models says what to know first.
• Status detection with Jev: Status detection in the settings. Kept in prefs.json; off unless you turn it on, and only from the machine itself.
• TypeSafe API key: API keys in the settings. Kept in keys.json with your agents' keys, never in prefs.json; set and cleared at the desk only, never shown back, and only ever sent to api.typesafe.ai.

In the state directory

Everything Flockdeck keeps is in one directory: %AppData%\flockdeck on Windows, ~/Library/Application Support/flockdeck on macOS, and ~/.config/flockdeck on Linux (or $XDG_CONFIG_HOME/flockdeck where that is set).

• agents.json: your own agents, changes to the built-in ones, the default agent and model, and the routing policy: for every project under defaults and routing, for one under projects. Agents and models describes it. It is read again each time the picker opens, so editing it needs no restart.
• keys.json: API keys set through Flockdeck, and the TypeSafe key. A key exported in the environment is used first, except for the TypeSafe key, where the one set in Settings is.
• remote.json: this machine's enrolment with the relay. flockdeck remote disable keeps it and marks it off; flockdeck remote remove removes it.
• routing.jsonl: what an older version's routing chose for each routed fan-out row, and whether you kept it. Nothing writes to it now. It holds the rule's name and the models, never the task. It keeps the last 10,000 lines, and Clear routing history empties it.
• keybindings.json: every shortcut you have remapped or cleared under Keyboard, by the action's own id; one absent from it is still its built-in binding. Delete it, or Reset every shortcut to its default, to put every shortcut back at once.
• prefs.json: the settings under General, Appearance and Terminal, the Jev switch under Status detection, Claude Code's usage limits, what paired devices are notified of, whether you have agreed to recording once, whether the help has been opened, and which hints were dismissed. Delete it while Flockdeck is not running to have the help open on the next start, every hint back, and every one of those settings as it first was.
• layout-….json: one per project: its tabs, splits and panes, with each pane's auto-approve read-only, lock and recording. flockdeck -new starts without it.
• projects.json: the recent projects the picker offers.
• session.json: which projects are reopened on the next start.
• error.log: why Flockdeck failed to start, when it had no terminal to say so in, and what went wrong as it stopped: a layout it could not save, an update it could not put in place, a restart that did not come back.
• instance.json: the address of the Flockdeck that is running, so a second launch joins it.
• updates: a downloaded release waiting to go in when Flockdeck next quits.
• sessions: the settings file written for each pane whose agent reports its status, which also carries the pane's status line where that goes through Flockdeck.
• chats: the built-in chat client's conversations.
• groups.json: the multi-repo projects' grouping.
• todos.json: the saved todo checklists of an older version. Nothing reads it now; it is left alone.
• worktree-procs.json: processes recorded for worktrees, so they can be swept up.
• e2e_key.json: this machine's end-to-end key for Flockdeck Remote terminals. It holds a secret; keep it private.
• recordings: the transcripts of recorded panes, and their exports; see Recording a pane.
• uploads: pictures attached from a phone, one folder per pane, removed after a week.
• window: the browser profile the window used to run in; nothing writes to it now, and it can be deleted. On Windows it is %LOCALAPPDATA%\flockdeck\window.

The window's web view keeps its own data outside this directory; on Windows, in %APPDATA%\flockdeck.exe.

To uninstall Flockdeck, quit it and delete the flockdeck binary (on Windows, the %LOCALAPPDATA%\Programs\flockdeck folder the installer made, its Start menu shortcut and its entry in your PATH), then this directory and, on Windows, %APPDATA%\flockdeck.exe; run flockdeck remote remove first if Flockdeck Remote is on, so the relay forgets the machine (removing the machine, like turning it off, keeps the account on the relay; flockdeck remote delete-account erases it). Worktrees it made are ordinary git worktrees, and stay beside their repositories until you remove them.

In the environment

These are read when Flockdeck starts, so set one where it will be seen then (setx NAME value on Windows, or an export line in your shell's profile elsewhere) and start Flockdeck again.

• FLOCKDECK_UPDATE: off stops Flockdeck checking for new releases at all, whatever Check for updates or Check for updates now in the settings says: no checks, in the background or asked for on the spot, and nothing already downloaded is put in place. That is what keeps an older version you installed on purpose from updating itself to the latest.
• FLOCKDECK_RELAY: which relay flockdeck remote enable uses.
• TYPESAFE_API_KEY: a key for TypeSafe's Jev, used only when Let TypeSafe's Jev help read pane status, under Status detection, is turned on; see Knowing who needs you. A key set in Settings › API keys › TypeSafe API key is used first; this is the fallback when none is set there. No other variable is ever tried. Without a key nothing is ever sent.
• ANTHROPIC_API_KEY, OPENAI_API_KEY and GEMINI_API_KEY (or GOOGLE_API_KEY): keys for the API agents talking to those vendors' own addresses, used before anything in keys.json. An agent given another address, such as a gateway's, is never sent them.
• FLOCKDECK_API_KEY: a key for any API agent, used when neither its own variables nor keys.json hold one.
• CLAUDE_CONFIG_DIR: where Claude Code keeps its own files; Flockdeck follows it to find conversations and folder trust.
• NO_COLOR: the built-in chat client draws without colour.
• FLOCKDECK_COLUMNS: the width the built-in chat client wraps its answers at. Without it the client follows the pane's width, falling back to COLUMNS and then 80.
• SHELL: the shell a shell pane runs, as a login shell; /bin/sh if it is unset or names a program that is not there. On Windows a shell pane runs pwsh if it is installed, then the shell COMSPEC names, then Windows PowerShell.

The variables Flockdeck sets in each pane, and the flags that shape one run, -agent, -new, -shell, are on The command line.