Docs / Getting started

Your first agent

Point Flotilla at a repository, describe a task, and watch an agent get to work in a checkout of its own.

Add a project

A project is a repository you want agents to work in. Agents never touch your own checkout of it: each one gets a fresh copy (a git worktree) on a branch of its own, so they can't trip over your work or each other's.

1. Click Add Project… in the sidebar, or press ⇧⌘N.
2. Click Add a repository folder… and pick the folder of a git repository.
3. Give the project a name and a color. The color shows next to each of its agents, which helps once you have a few projects.
4. Click Add Project.

Start an agent

1. Press ⌘N, or click the + next to the project's name.
2. Describe the task, the way you'd ask the agent directly. For example: "Add a dark mode toggle to the settings page."
3. Leave the name empty and Flotilla names the agent after its task, using Apple Intelligence on your Mac. Or type a short name yourself.
4. Pick the agent to run: Claude, Codex or Cursor.
5. Press ↩ to create it.

By default the agent starts on a new branch from the latest version of your main branch. Flotilla checks out its worktree, starts the agent in a pane, and hands it your task.

Watch it work

The agent's pane is a real terminal running Claude Code, Codex or Cursor, exactly as you'd run it yourself. Type into it to talk to the agent, answer its questions or give it more to do.

Meanwhile, its row in the sidebar shows what it's up to: working, waiting on you, or done. You don't need to keep watching the pane; Flotilla tells you when the agent needs you.

Start a few more

This is where Flotilla shines. Press ⌘N again and give a second agent a different task. Each gets its own checkout and its own pane, and the sidebar keeps track of all of them.