Sessions, spaces, tabs, and panes

flockr arranges terminals in four levels:

• Session: one flockr server and everything it runs.
• Space: a named group of tabs, usually one per project. The CLI and API call spaces workspaces.
• Tab: one layout of panes inside a space.
• Pane: one terminal. A pane may run a shell, an editor, a server, or a coding agent.

Sessions

Running flockr starts a server in the background and attaches your terminal to it as a client. The server owns every pane. When you detach (prefix+q) or close the terminal, the server and its processes keep running. Run flockr again to attach.

Named sessions

By default you use the session named default. Use --session to start or attach to a separate session with its own server:

flockr --session work
flockr session attach work

Session names may use ASCII letters, numbers, ., _, and -, up to 64 bytes.

Manage sessions with:

flockr session list           # name, status, directory, and socket of each session
flockr session stop work      # stop a session's server
flockr session delete work    # delete a stopped session

You cannot delete the default session.

Where session data lives

Each session directory holds its API socket (flockr.sock), its saved layout (session.json), and its log files. All sessions share one config.toml.

Persistence and restore

flockr saves your spaces, tabs, layouts, and each pane's working directory to session.json. When the server restarts, it restores them, and each pane gets a fresh shell in its saved directory.

• Agents: with session.resume_agents_on_restore = true (the default), supported agents resume into their own conversation sessions. This needs an official integration, which reports the agent's session to flockr. Resumed agents keep the CLI options they were started with.
• Spacing: session.startup_per_agent_delay_ms (default 100) spaces out agent restores. 0 starts them all at once.
• Screen history: experimental.pane_history = true also saves recent pane screen history across full server restarts, in session-history.json.

To stop a server and all its pane processes, run flockr server stop. Don't run it from inside a session you want to keep.

Spaces

Create a space with prefix+shift+n, rename it with prefix+shift+w, and close it with prefix+shift+d. flockr asks before closing unless ui.confirm_close = false.

prefix+w opens navigate mode, where you move through spaces with the arrow keys, switch with 1..9, and press m to grab a space and move it.

Tabs

Create a tab with prefix+c. Switch with prefix+n, prefix+p, or prefix+1..9. Close with prefix+shift+x. By default flockr asks for a name for each new tab; set ui.prompt_new_tab_name = false to skip it. ui.hide_tab_bar_when_single_tab hides the tab row when a space has one tab.

Panes

Split with prefix+v (side by side) or prefix+minus (stacked). Move focus with prefix+h/j/k/l. Zoom one pane with prefix+z. Close with prefix+x. See Keybindings for layout presets and resize keys.

Where new panes start

terminal.new_cwd sets the working directory for new panes, tabs, and spaces:

• "follow" (default): inherit from the source pane or space.
• "home": $HOME.
• "current": flockr's own process directory.
• A fixed path such as "~/Projects".

New panes run terminal.default_shell, or $SHELL, then /bin/sh.

IDs

The CLI and API name things with short IDs: space w1, tab w1:t1, pane w1:p1. Closed tab and pane IDs are not reused. Every pane gets FLOCKR_WORKSPACE_ID, FLOCKR_TAB_ID, and FLOCKR_PANE_ID in its environment, plus FLOCKR_ENV=1.

Worktree spaces

A worktree space is a space backed by its own Git worktree, so an agent can work on a branch without touching your main checkout.

• prefix+shift+g creates a Git worktree from the selected space and opens it as a new space.
• Worktrees go under worktrees.directory, default ~/.flockr/worktrees.
• In the sidebar, worktree spaces nest under their repo. Their agents nest the same way in the agents list.
• Worktree spaces show commits ahead and behind, and uncommitted changes (diff_stat), like any space.
• open_worktree and remove_worktree have no default keys. Bind them in [keys] if you want them. Removing opens a confirmation.

From the command line:

flockr worktree create --branch fix-login --base master
flockr worktree open --branch fix-login
flockr worktree list
flockr worktree remove --workspace w4

See the CLI reference for every option.