Quickstart

Before you take off

• flock itself. macOS 12 or later on Apple Silicon. Download the DMG, drag it into Applications, open it. Builds are signed and notarized. See Install.
• At least one agent CLI, installed and logged in. flock drives claude (Claude Code), grok, opencode, codex and pi. You pick one per workspace and can mix kinds inside it later. Agents run on your own model credentials; flock never resells tokens.
• Docker Desktop. Optional, strongly recommended, and worth installing before your first workspace: it powers both Secure Mode and the Graph. Turn on Start at login so neither is ever half-available.
• A flock ID. First launch asks you to sign in and claim a handle. That handle is how friends add you and how presence travels. See Your flock ID.

GitHub can wait until step five. Everything up to that point works offline from the network's point of view, minus whatever your agents call.

1. Your first workspace

A workspace is a repo plus its agents. Press ⌘N, or click + next to Workspaces in the sidebar. The dialog is short, but every field in it is a decision worth making once and then reusing:

Press ⏎ to create it. The chosen agent launches in every pane at once.

Pick the branch mode deliberately

New branch is the default and the one to keep. Every agent gets its own git worktree and its own branch, cut from the base ref you choose, so four agents on one repo never fight over one checkout or one index. Leave Fetch base first on and nobody starts on a stale main. Worktrees live under ~/.flock/worktrees/ (configurable in Settings) and are cleaned up when their pane closes. A fresh worktree only contains tracked files, so flock copies your .env*, .envrc and .tool-versions in for you; edit that list in Settings if your repo needs more.

Existing checks out a branch you already have in its own worktree, which is how you continue yesterday's work. If that branch is already checked out somewhere, flock joins that folder rather than refusing, and says so in the dialog.

Current checkout puts every agent in your working copy with no isolation at all. Fine for a single agent doing something small, painful the moment two of them edit at once.

Start with two agents, not twelve

The twelve-pane layout is real and people use it, but the useful ceiling on day one is two. Add panes as fast as you can keep up with them, which is the actual constraint. On the Free plan you get 2 workspaces and 2 agents per workspace; Individual lifts both.

Leave Secure Mode on

flock launches agents with their permission prompts turned off, on purpose: an agent that stops to ask about every file is an agent you are babysitting rather than flying. The container is what makes that defensible. A jailed agent sees your repo and nothing else, no keys, no home directory, no other repos, and logs in once to its own persistent home. The first secure pane builds the sandbox image in the terminal, a few minutes, once. Details and the honest fine print live in Secure Mode.

2. Fly the panes

Each pane is a real terminal running a real agent, not a chat box wrapped around one. Click a pane and type. Every agent gets a name on spawn, so the sidebar reads like a roster: Vesper is working, Pluto needs input.

Status is ambient. flock reads each terminal and keeps a live one-line label of what that agent is doing, rolled up into sidebar rows, workspace cards and tab dots. A background tab with an agent waiting on you shows a pulsing dot. You never have to poll the grid to find out who is stuck.

Move by keyboard. ⌘J jumps to the next agent waiting on you, across every tab in the workspace, which is the single most useful key in the app. ⌘] and ⌘[ walk panes in order, ⌘1 to ⌘9 switch tabs, and ⌘K opens the command palette, where anything that needs you sorts to the top regardless of what you type.

Give agents context the fast way. Drag files onto a pane to paste their paths. Paste a screenshot straight into the terminal and flock stages the image and types its path for you. Hold the voice hotkey and talk, transcribed on-device, and the text lands in the focused pane as typed input. See Voice.

Watch the context meter. Claude Code and Grok panes carry a small bar in their top bar showing how full that agent's context window is. It warms at 60% and goes hot at 85%, which is your cue to land the current thread and start a fresh agent rather than let the conversation compact out from under it.

Read the work, not just the output. The git panel under a workspace card maps every agent to its branch, shows how dirty each checkout is and how far ahead or behind, and opens the diff. It is the fastest way to answer "what did the last hour actually produce".

3. Grow the formation

• ⌘D splits the focused pane right with a fresh agent, ⌘⇧D splits it down.
• ⌘T opens a new tab with its own layout, so one tab can be feature work and another a debugging session.
• Right-click a pane or empty grid to spawn a specific kind: Spawn Claude Code, Spawn Grok, Spawn OpenCode, Spawn Codex, Spawn Pi. Mixed workspaces are normal, and each kind is colour-coded so you can tell them apart at a glance.
• Bring In Agent and Bring In Workspace lay out agents from another workspace in this tab. The agent keeps running where it lives, and closing the tab you borrowed it into just returns it.
• ⌘Z zooms a pane to full screen. The ⧉ button in a pane's top bar detaches it into its own window for another display, and it always folds back into the tab it came from. See Pop-out windows.
• ⌘+ and ⌘- size the agent text you spend the day reading. Add ⌥ to scale the app chrome around it instead.

Workspaces persist hard: quit flock and relaunch, and your layouts respawn their agents in place, each terminal repainted with its pre-restart scrollback. Claude Code agents resume their actual conversation (--resume), so a relaunch drops you mid-thought. Closing the laptop is not a decision you have to plan around.

4. Give them one memory

This is the step most people skip and later wish they had not. The Graph is a local knowledge graph your agents share over MCP: decisions made, approaches tried and failed, which agent owns which file. Agent B picks up where Agent A left off instead of rediscovering the same ground, and next week's agent does not re-learn what this week's agent already paid for.

Setup is three steps: start Docker, enable the graph in Settings → Graph and press Start the engine, then register the bundled MCP server with your agent CLI using the snippet the setup guide gives you. flock exports each pane's identity into its environment, so writes are attributed to the right agent and workspace with no prompting from you.

Do it on day one. The value compounds, which also means an empty graph is worth nothing and a month-old one is worth a lot.

5. Wire up the rest

The Quick actions panel in the sidebar tracks this list and ticks items off as you finish them:

• Live agent status. One click installs the status hook for your agent CLI, which is what makes the sidebar's per-agent labels precise rather than inferred. Reversible in Settings → Integrations.
• GitHub. Device-flow sign-in, or flock picks up your gh CLI token. You get open PRs in the sidebar, CI status for your branch in the top bar, one-click review that checks out the PR's exact head commit and spawns an agent on it, and an ordered merge queue. See PR review.
• Voice. Enable it, download a Whisper model, pick a hotkey. Everything stays on your machine.
• A budget. Settings lets you set a daily or monthly spend ceiling and warns you as you approach it. Treat it as a guardrail, not an invoice: token counts are exact, the dollars come from a local price table.
• Usage gauges. The status bar keeps live limits for every agent CLI you run, so you know your burn without leaving the app. See Usage.

Best practices

Everything above gets agents running. This is what makes them worth running.

One agent, one branch

Isolation is the whole reason parallel agents work at all. Keep the branch mode on New branch so every agent has its own worktree, and let flock name the branches. Two agents sharing a checkout will spend your afternoon undoing each other, and you will read it as "the models are bad at this" when it was a git problem.

Never run more agents than you can review

Agent output you have not read is not throughput, it is inventory. Two agents you review carefully beat six you skim. Scale up when reviewing is the thing you are waiting on.

This is the real ceiling now. Model capacity is cheap and getting cheaper; the scarce thing is how much of a formation one person can brief precisely, watch honestly and correct early. Every habit below is about spending that attention well.

Brief like a colleague, not a search box

Give each agent the goal, the constraints, and what done looks like. Point at the files, paste the screenshot, name the test that has to pass. Because panes are real terminals, everything your agent CLI already reads still applies: your project's agent instructions file, its config, its MCP servers. flock adds the formation, not a new prompt format.

Answer blockers first, then read finished work

A blocked agent costs you the whole time it sits there. Start every pass with ⌘J until nothing is waiting, then go read diffs. The command palette's attention rows are the same list if you would rather see it at once.

Queue prompts instead of interrupting yourself

⌘⇧P captures a prompt, with screenshots attached, into a personal queue without needing a pane. Launch it into any running agent later from the sidebar. Two more moves in the pane's right-click menu complete the loop: Send to Prompt Queue lifts a half-typed prompt out of a pane and saves it, and Insert from Prompt Queue drops a saved one in. Ideas arrive while agents work; this is where they go.

Race when you do not know the shape of the answer

Right-click a workspace and pick Race Agents…: one prompt, 2 to 6 agents, each in its own worktree off the same commit, started with ⌘⏎. When they finish you compare their diffs against that shared starting point and merge exactly one. It costs more tokens and saves the afternoon you would have spent picking an approach by argument. Contender branches are prefixed race- so they are never confused with branches you cut by hand.

Broadcast when the instruction is fleet-wide

The sync button in the tab header replicates what you type into every visible pane in that tab. Use it for "run the test suite and report back" across a formation. It is deliberately off after a restart, because a sync mode that survives quietly is a footgun.

Land threads before they compact

When a pane's context meter goes hot, the agent is about to lose its earliest context. Have it write down where it got to, ideally into the graph, then close the pane and spawn a fresh one. A new agent with a good brief beats an old agent with an amputated memory.

Keep the graph fed

Ask agents to record decisions and failed attempts as they work, not at the end. The dead ends are the valuable part: a recorded failure is the one thing that stops the next agent, or the next teammate, from paying for it twice.

Route work to people, not to chat

When someone else's machine, checkout or context is the right one, hand the task over instead of describing it. Watch a friend's agent live, send a brief straight into their agent, or open a shared workspace where you can both spawn and type. See Collaboration.

A day in formation

One concrete routine, to make the above less abstract:

1. Open flock. Yesterday's workspaces respawn with their scrollback. ⌘K tells you who was left waiting overnight.
2. Empty the queue. Launch the prompts you captured yesterday evening into fresh panes, one branch each.
3. Set the formation. Say four agents: one on the feature, one on tests for what landed yesterday, one reviewing an open PR, one racing an approach you are unsure about.
4. Loop. ⌘J to whoever is blocked, answer, then read one finished diff in the git panel and merge or queue it. Capture new ideas with ⌘⇧P as they occur instead of derailing what is running.
5. Close the loop. Merge the race winner, queue the PRs, let agents record what they learned into the graph.
6. Leave them flying. Long jobs keep running. Quit if you want; the formation comes back where you left it.

Where to go next

• Workspaces: tabs, panes, worktrees and how status rolls up.
• Keyboard shortcuts: the full list.
• The Graph: setup, the MCP tools agents get, and team hosting.
• Secure Mode: what the jail does and does not cover.
• Troubleshooting: the problems people actually hit.