troubleshooting

Gatekeeper blocks the app

The download was probably truncated. Check it:

spctl --assess --type open --context context:primary-signature -vv ~/Downloads/Fleet-*.dmg

That should say accepted and source=Notarized Developer ID. If it does not, re-download.

An update went back to the old version

The sidebar banner reads Stayed on Fleet and names the version you are still on. The new version was handed your sessions and, during its two-minute trial, crashed, stopped responding, stopped reading a terminal, or never confirmed it had them. The version you were on took every session back, along with any opened during the trial, and put its own app back in place.

That version is not installed again on its own, and checking for updates by hand does not bring it back either. Report… opens an issue about it in your browser. It stays listed under Settings → Updates → Rolled back, where Allow Again lets it install once more; a later release is offered as usual.

Notifications never appear

Only a build you compiled yourself does this. macOS refuses notifications to any app whose signature has no Team Identifier, and an ad-hoc or self-signed build has none — so no permission prompt appears and no entry shows up in System Settings → Notifications. Check a copy with:

codesign -dv --verbose=2 /Applications/Fleet.app | grep TeamIdentifier

No TeamIdentifier line means no notifications. Replace that build with the download. Until you do, the Dock badge and menu-bar extra still count sessions that need you, and ⌘⇧J still jumps to the next one.

Notifications are allowed but nothing shows

Fleet’s alert style is set to None, so its notifications go straight to Notification Center without a banner. macOS reports this as permission granted, which is why the switches under Settings → Notifications look fine.

Settings names this when it is the case — a warning above the switches, with a button to the right pane of System Settings.

Agent sessions show as plain shell rows

The fleet plugin is not installed, or its hooks cannot run.

1. If the session was already open when you ran setup, tell it to look again. A plugin’s hooks are loaded when a session starts, so an older session reports nothing until it does. In Claude Code that is /reload-plugins; Codex and Antigravity have no equivalent, so start a new session. This is the common one.
2. Run setup for that agent — Settings (⌘,) has a section for each one found on your Mac. It is safe to re-run.
3. Check that Node is on your PATH — the hooks are Node scripts. Run which node inside a Fleet session, not just in your login shell, since a version manager may only be initialised for interactive shells.
4. Confirm files are appearing in ~/.fleet/session-status/state/.

If a Claude session sets CLAUDE_CONFIG_DIR, Fleet has to know about that directory to install into it. It finds ~/.claude and any ~/.claude* you are using on its own; one anywhere else has to be added under Settings → Claude Code integration → Add Config Directory….

The integration is set up but rows are inert

Most likely the fleet plugin has been switched off. A plugin’s hooks run only while the agent has that plugin enabled, and switching it off silences every row at once — the files are all still there, so nothing looks wrong.

In Settings, the Claude Code section reads Set up, but not reporting when that is the case, and offers to turn the plugin back on; the Codex and Antigravity sections say it is switched off and name the command that turns it on. Sessions already open still need /reload-plugins, or a restart, afterwards.

Codex has a second way to be silent: it runs no hook it has not been told to trust, and an untrusted one is listed, enabled, and never runs. Its section names that too, and the button becomes Repair Codex Integration.

Status is stuck on “Working”

Usually the turn failed. An API error — overloaded, a dropped connection, a rate limit — or an expired login ends the turn without firing any hook, so the state file stays frozen on whatever it last said. Fleet reads both from the transcript and puts them on the row: API error · 529 Overloaded, or Login required.

If the row still says Working, Fleet flags it itself: a session reporting working with no terminal output for a while is marked stalled. That is usually the agent exiting without its stop hook firing — a crash, or a kill. Sending any input to the session, or closing and reopening it, clears the state.

A session shows the wrong name

Two things can name a session: Claude’s /rename, and your own rename from double-clicking the row title. The most recent one wins. If Claude renamed a session after you did, rename it again from the sidebar.

No activity subtitle under a session

Check Settings → Activity & detection → Session activity subtitles, which is on by default but can be switched off, and that Detail is not under Hidden in Settings → Sidebar Rows.

Otherwise, on the status’s line, where it sits by default, the detail only appears while a session is working; move it to a line of its own to keep it after the turn ends. Claude Code’s detail is read from the session’s transcript, and Codex’s and Antigravity’s from their hooks, so a plain shell has none, and neither does a session whose row is not reporting its status at all. That is the problem covered above.

A folder looks empty inside a session

macOS asks about Desktop, Documents and Downloads one at a time, and a shell Fleet started inherits the answer Fleet got. Settings → Permissions will walk all three now rather than leaving them to turn up mid-task, and Full Disk Access covers every protected folder at once if you would rather not be asked at all.

macOS will not ask again about anything you denied — Files & Folders in System Settings is the only place that can change it, and the pane links there.

Something else

Worth gathering before you dig in: your macOS version, the Fleet version from Fleet → About, whether the status layer is installed, and what you were doing when it went wrong. Most problems above come down to one of Gatekeeper, PATH, or a hook that never fired.

If none of them fit, send those details to help@fleet-terminal.app. Ideas for things Fleet should do are welcome at the same address.

There is also a Discord, which is the faster of the two if someone else has already hit the same thing.