FlotillaDocs / Reference
Troubleshooting
Something not quite right? Start here. Most problems come down to a missing tool or a setting, and Flotilla can usually tell you which.
First stop for almost anything: Settings › Setup. It checks every tool the way your agents see them and says what needs fixing.
An agent's status never changes
Flotilla learns what agents are doing from a hook each agent runs.
- Codex: Codex only runs a hook you've trusted. Type
/hooksin a Codex pane and trust Flotilla's. - Cursor: turn on the Third-Party Imports setting in Cursor so it picks up the hook.
- Any agent: check that "Flotilla hook and CLI" is green in Settings › Setup.
Pull requests don't show up
- Check that "GitHub CLI" is green in Settings › Setup. If not, run
gh auth loginin Terminal. - Check that GitHub integration is on in Settings › GitHub.
- The PRs list in the sidebar shows only pull requests you opened. An agent's own tab shows every pull request on the branches it worked on.
An agent says it's asleep
It was put to sleep to save memory. Press ↩ in its pane or click Resume, and it carries on with its conversation. To stop it happening, see Let idle agents sleep.
Flotilla won't say it's safe to delete an agent
It's protecting something: the agent is still working, its pull request is open, or it has changes that aren't committed or pushed. The alert lists exactly what. Deal with it, or choose Delete Anyway if you don't need it.
"Worktree missing"
The agent's checkout was deleted outside Flotilla. Right-click the agent and choose Recreate Worktree to check its branch out again.
The flotilla command says "Flotilla is not running"
The command talks to the app, so Flotilla needs to be open. Open it and try again.
"Part of Flotilla Pro" or a lock icon
That feature or item is past the free plan's limits. See Free and Pro.
What happens to agents when I quit?
Flotilla tells you before quitting. Without Keep agents running across restarts, agents stop and each conversation resumes the next time you open it. With it, they keep working in the background.
Still stuck?
Choose Send Feedback… from the Help menu (it shows while crash reports and usage data are on) to send a note straight to the developer, with your email if you'd like a reply. You can include a screenshot of the window. Or email hello@tinypenguin.com.