Docs / Going further

Running many agents

Once a few agents feel natural, here's how to choose where each one works, try two approaches at once, and keep a big fleet light.

Choose where an agent works

New agents start on a fresh branch from the latest main branch. That's right most of the time, but the New Agent sheet (⌘N) has other options under From:

• New branch from another branch, to build on work that isn't merged yet.
• Work in an existing branch, to pick up where someone left off.
• Work in the main checkout, your own copy of the repo, when you want to see the agent's edits there directly.
• Work in another agent's checkout, to have a second agent help on the same branch.

If a project's agents should always use the main checkout, set that once under New agents in Edit Project.

Try two approaches

Not sure which way to go? Right-click an agent and choose Fork Session…. The fork starts with the whole conversation so far, in its own checkout, so you can send each one down a different path and keep the better result.

Find any agent

With a dozen agents running, press ⌘O and type. Flotilla finds agents by name, branch, pull request, task, a file they touched, or even something said in their conversation. Deleted agents show up too.

Holding ⌥ shows a number next to the first nine agents in the sidebar; ⌥1 to ⌥9 opens them.

Start agents instantly PRO

Checking out a big repo takes a moment. In Edit Project, unfold Ready worktrees, sleeping agents, repo settings and choose how many worktrees to keep ready. New agents then start in one straight away, and each deleted agent's worktree is replaced with a fresh one.

If every new worktree needs the same setup, like installing dependencies or copying a .env file, put it in the repo's settings and Flotilla does it before an agent arrives. See Repo settings.

Let idle agents sleep PRO

An agent that's done and waiting still uses memory. Flotilla can put idle agents to sleep after a while (30 minutes, unless you change it in Settings › Agents). A sleeping agent keeps its last screen; press ↩ in its pane or click Resume and it carries on with its conversation.

You can change this for a project in Edit Project, or for a single agent by right-clicking it and choosing Sleep When Idle or Sleep Now. When your Mac runs low on memory, Flotilla puts idle agents to sleep sooner.

Keep agents running when you quit PRO

Turn on Keep agents running across restarts in Settings › Agents, and agents carry on in the background when you quit, update or restart Flotilla. Open it again and every pane is right where you left it.

Without it, quitting stops the agents. Their conversations are saved, and each one resumes when you open it next time.

Projects with several repos PRO

If your work spans repositories, like an app and its API, add them all to one project. Each agent gets a checkout of every repo and starts in the first one.