Using Flockdeck

Panes and tabs

A pane is one terminal running one agent, or a plain shell. Tabs hold panes, and a tab can hold one or several, split however you like.

Making them

Keys	What it makes
`Ctrl+Shift+T`	A tab with one agent in it
`Ctrl+Shift+N`	A tab with a plain shell (no agent, no hooks)
`Ctrl+Shift+D`	An agent beside the focused pane
`Ctrl+Shift+E`	An agent below the focused pane
Split right (shell)	A shell beside the focused pane, from the command palette

Each of those takes the project's default agent, which keeps making a pane one keystroke. To choose a different agent or a different model, click the ▾ beside the + that opens a new tab, or take the two picker entries out of the command palette; Agents and models is the page for all of it. The pane header then names what it got, beside the branch.

A shell pane is an ordinary terminal in the same directory. It is there for the git, npm or go command you want to run yourself while the agents work, and for watching a build. That is why it can be split in beside an agent as well as opened in a tab of its own.

Working in them

Click a pane to give it the keyboard. Everything you type goes to the agent in it. That is the point, and it is why almost all of this application's own shortcuts are on Ctrl+Shift, which agents do not use.

Drag the divider between two panes to resize them, or reach it with Tab and use the arrow keys, and Home to share the room equally again.
Ctrl+Shift+Z gives the focused pane the whole tab, and gives it back; so does double-clicking the pane's header. The others keep running; they are simply not on screen.
Ctrl+Shift+F searches the focused terminal's scrollback.
Select text with the mouse and Ctrl+C copies it; Ctrl+V pastes. With nothing selected, Ctrl+C goes to the agent, as it always did. Keyboard shortcuts has the rest, and macOS.
Ctrl+Shift+W closes a pane and stops the agent in it, without asking. It also ends what was started in the pane and is still running there: a shell's background jobs, a server an agent left going, a job that ignores the hangup. A program with windows of its own (a browser, an editor started with code .) stays open, as it does when a terminal is closed, and so does what it runs, such as the terminals in that editor. On macOS a background job that ignores the hangup (nohup) keeps running. Closing a tab's last pane closes the tab, and the × on a tab, or a click on it with the middle button, closes every pane in it.

The buttons in a pane header, in order: include in broadcast (⇉), auto-approve read-only (✓), restart, zoom, export transcript, record, pane info (ⓘ), lock, close. Auto-approve read-only is off until you turn it on, pane by pane (the ✓'s tooltip counts the commands it has let through unasked so far), and the pane keeps the setting across a restart of Flockdeck: see Knowing who needs you. Record is off until you turn it on too; export and record are not shown on a shell pane, which has no conversation. Showing the transcript file in your file manager is in Ctrl+Shift+Y and the command palette rather than the header, and works only in a window on the machine Flockdeck runs on: see Recording a pane.

One pane, several windows

A pane has one terminal however many windows show it (a second window, a phone over Flockdeck Remote), and that terminal is the size of the window last used on it: the one you focus or type in. Every other window draws it at that same size, so what the agent prints lands where it should. Where that is larger than the pane's room in a window, the window shows the part of it nearest the bottom left, where the latest lines are, with a note such as Viewing 120×40 · fit to this window; click it to size the pane for this window instead. A pane's terminal is never made smaller than 20 columns by 5 rows or larger than 500 by 200.

Pane info

Ctrl+Shift+Y, in the command palette and as the ⓘ in the pane header, lists what names a pane in files, logs and commands, each with a Copy button, and Copy all puts the whole list on the clipboard as plain text. A value the pane does not have yet says "not set". The list has:

The pane id, which flockdeck close takes and which transcript files hold as pane.
The pane's name, its project and project folder, its directory (a worktree has its own), its branch and its tab.
For an agent, the agent, the model and the conversation id, which is the agent's own id for the conversation. It changes after /clear. The first 8 characters of it are in a transcript's file name, and it is the file name of the conversation the agent stores under ~/.claude/projects.
The process id, the peer name set by flockdeck peer-name, and the pane's status.
Whether the pane is recording, the path of its transcript file (the one it is recording to, or its latest export, with a Show in folder button that selects it in your file manager) and the path of the conversation file the agent stores itself. That last path is shown for panes that run Claude Code (including a second Claude account) and for Flockdeck's own API agents, once the agent has written the file. Until then, and for every other agent, it says "not set". Only Claude Code panes can be exported or recorded, so an API agent's transcript path always says "not set".

A shell has no agent, conversation or transcript, so those are left out for it. Nothing secret is listed: no keys, tokens or environment. A path can name your own folders, so look at Copy all before pasting it somewhere public. The list is read on the machine Flockdeck runs on and is not sent anywhere else, so a window reached through Flockdeck Remote cannot open it.

Finding a pane

Ctrl+Shift+L, in the command palette, searches every pane in every open project. Type part of a pane's name, project, tab, agent, model, directory, branch, pane id, conversation id, process id or peer name; several words must all match, in any of those, and case does not matter. A conversation id matches from its first characters, so the 8 in a transcript's file name will do. Each result shows the pane, its project and tab, and what matched. Press Enter for the first result or click one: Flockdeck goes to that project and tab and gives the pane the keyboard. Esc closes the search. All agents across projects lists the same panes by what needs you, rather than by what you type.

Locking a pane

Lock pane, in the command palette and as the padlock in the pane header, locks a pane so it cannot be closed by accident. The same action unlocks it again, and the palette names it Unlock pane while the pane is locked. A locked pane shows a padlock and the word "Locked" in its header, and while it is locked:

Ctrl+Shift+W and the × in its header do nothing but say the pane is locked.
Its tab cannot be closed, by the × on the tab or the middle button, while any pane in it is locked, and neither can a project that holds one.
Close finished panes leaves it open and says how many it left.
flockdeck close refuses it, and -force does not change that: -force is for a pane still working, and a lock is something only you undo. flockdeck close -finished skips it and reports how many it skipped.

Restart pane still works on a locked pane and leaves it locked. The lock is kept with the layout, so it survives a restart of Flockdeck, and it moves with the pane when you drag it to another tab. Quitting Flockdeck is not closing a pane, so a lock does not stop it.

Naming a tab

A tab names itself after the first thing its agent is asked. To call it something else, double-click it, press F2 while the keyboard is on it, or choose Rename this tab… in the command palette; a name you give it stays, whatever the agent is asked next. To go back, rename it to an empty name or choose Use the automatic title in the same dialog: the tab takes the title it would have had if it had never been renamed. Either way the name is kept with the layout.

Restarting

Restart pane, in the command palette and in the pane header, stops the process and starts it again in the same directory, with the same agent and model. It resumes the same conversation where that agent can, because a pane and its conversation are one identity. Use it when an agent is stuck or has wedged itself, not to clear the screen.

A pane whose process exits covers its terminal with what happened and two buttons, Restart and Close pane, rather than leaving a dead black rectangle.