Skip to content

Troubleshooting

The failure modes people actually hit, and what each one means.

Gatekeeper blocks the app

It should not. Fleet 0.1.0 is signed with a Developer ID certificate, notarized by Apple and stapled, so it opens on a clean machine with no warning.

If you do see one, the download was probably truncated. Check it:

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

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

Notifications never appear

This is the same root cause as above, and it is not a bug you can configure around.

UNUserNotificationCenter.requestAuthorization refuses any application whose signature has no real Team Identifier — and codesign only sets one when the certificate chains to Apple’s CA. An ad-hoc or self-signed build therefore gets Error Code=1 "Notifications are not allowed for this application", no permission prompt appears, and no entry shows up in System Settings → Notifications.

It resolves when Fleet is signed with a Developer ID Application (or Apple Development) certificate, which is on the roadmap. You can check any build for yourself with:

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

No TeamIdentifier line means no notifications. In the meantime the Dock badge and menu-bar extra still count sessions that need you, and ⌘⇧J still jumps to the next one.

Claude sessions show as plain shell rows

The status layer is not installed, or the hooks cannot run.

  1. Run Settings (⌘,) → Claude → Set up Claude Integration. It is safe to re-run.
  2. 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.
  3. Confirm files are appearing in ~/.claude/session-status/state/.

Status is stuck on “Working”

Fleet flags this itself: a session reporting working with no terminal output for a while is marked as stalled.

Usually it means Claude exited 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, read from ~/.claude/sessions/<pid>.json, 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.

AI summaries never appear

Summaries are opt-in — check Settings → AI. They also only run while a session is actually working, and they are throttled, so a fast-finishing session may never get one.

Fleet invokes claude -p --model claude-haiku-4-5 with --setting-sources "" --strict-mcp-config and FLEET_SUMMARY=1, reusing your normal Claude login. If claude is not on the PATH inside a Fleet session, summaries silently do nothing.

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.