Using Flockdeck

The command line

Once it is running you rarely need the command line: projects are opened and switched from inside the window. These are what is left.

Running the binary again does not start a second set of agents. It finds the instance already going, hands it the directory you asked for, and opens a window onto it. -solo is the escape hatch when you genuinely want two.

-new is not a way to glance at an empty window. Its layout is saved over the one it skipped within half a minute of starting, and again when the run ends. The other projects you had open are put back in the list when the run ends, so the next start reopens them as before, around the one this run was started on, which is where it lands. One you closed during the run stays closed. A run that crashes after its window was reloaded or detached has already written the list without them, and the next start opens only its own projects.

spawn

Run from inside a pane, this starts another agent:

flockdeck spawn [--worktree <branch>] [--split] [--shell]
                [--agent <id>] [--model <model>] <task>

--agent and --model choose which agent the helper is; without them it is whatever the project runs by default. flockdeck agents lists the names both of them take, and a name neither the catalog nor the agent has is answered here rather than becoming a pane that never starts.

The address and token come from the environment the pane was started with — FLOCKDECK_API and FLOCKDECK_TOKEN below — so only processes running inside a pane can use it, and running it anywhere else says so rather than failing obscurely. That is what lets an agent hand work to helpers of its own.

keys

An API agent — one Flockdeck talks to directly rather than through a CLI of its own — needs a key. It is looked for in that agent's own environment variables first, then in keys.json in the state directory, and last in FLOCKDECK_API_KEY. A vendor's own variable, such as OPENAI_API_KEY, is read only while the agent talks to that vendor's own address.

Nothing here ever prints a key back, and neither does the interface.

remote

Reach this machine's agents from another device, through a relay.

A running instance is told when enable or disable changes anything, and connects or disconnects on the spot. Remote access has the rest.

chat

flockdeck chat

This is the terminal chat client Flockdeck runs in a pane for an API agent — the one that talks to a model API itself, with no wrapper CLI, no node and no Python. It is told which agent, which model and which session to be; the pane fills all three in, which is why you meet it as a pane rather than type it. Run outside a pane it still works, but there is nothing listening for the lifecycle events it reports, so nothing turns amber when it wants you. It has flags of its own for setting it up by hand — which wire to speak, the base URL, the model, and which environment variable holds the key — and lists them when asked for help, for talking to an endpoint from a plain terminal. On Windows, run it as flockdeck-chat chat: flockdeck.exe is built without a console, so it has nowhere to draw the conversation, and flockdeck-chat.exe beside it is the same program built with one.

update

When a new version has been downloaded, an Update button appears at the right of the top bar. It offers Restart now, which saves and reopens your layout but stops the running agents, or Later, which installs it when Flockdeck next quits. A window reached through the relay is not shown the button, and cannot turn the check for updates on or off: both are done at the desk.

Releases are published at dl.flockdeck.ai as one archive per platform, with a checksums.txt beside them, signed with the release key that is built into Flockdeck. A second, standby key, held offline and used only if the first is ever lost or compromised, has been trusted alongside it since v0.3.5. GitHub carries every release too, signed the same way: when dl.flockdeck.ai cannot be reached, or what it serves is not signed by a trusted key, Flockdeck downloads from GitHub instead and says why in its log. Wherever it comes from, the download is checked against its signed SHA-256 before anything is replaced, and a download that does not match is thrown away rather than installed.

Which release is the latest comes from latest.json on dl.flockdeck.ai, which only names a version; Flockdeck then reads that version's own signed manifest. So an out-of-date latest.json can hold an update back for a few minutes, but it can never have anything unsigned or older installed.

Replacing the binary does not disturb an instance that is already running: it is running from an image the operating system already holds, so the new version is simply what starts next time. The old file is moved aside and swept up by the following start.

A build you made yourself — stamped dev by go build or go install, or by git describe when built with make — is never replaced by a release: there is no sense in which it is behind one.

Set FLOCKDECK_UPDATE=off to stop the window checking on its own, and to stop an update it has already downloaded being put in place when Flockdeck exits. The subcommand still works; it is the background updating that goes.

Environment

FLOCKDECK_PANE, FLOCKDECK_PANE_NAME and FLOCKDECK_PROJECT are what a shell pane — which has no lifecycle hooks of its own — has to go on.

FLOCKDECK_API, FLOCKDECK_TOKEN, FLOCKDECK_PANE, FLOCKDECK_PANE_NAME and FLOCKDECK_PROJECT were called PERCH_* before the program was renamed. Panes still carry both spellings of those five and spawn still reads both, so a prompt or a script written against the old names keeps working; they will go in a later release. FLOCKDECK_AGENT, FLOCKDECK_MODEL and FLOCKDECK_LAUNCH are newer and have only the one name.