configuration

The two files

Fleet keeps its settings and session state in ~/.config/fleet-terminal/.

config.json — settings

Theme, font, cursor style, terminal behaviour, how sidebar rows are laid out, notification rules, AI options, launch profiles. Everything here is editable from the searchable Settings panel (⌘,), which is the recommended route — but the file is plain JSON if you would rather edit it directly.

state.json — open sessions

The sessions you had open, and for each one its working directory, custom name, colour, group, position and the agent conversation it last had. It is saved whenever any of that changes (an agent started in a pane, a /clear), and is what gets restored on launch.

Appearance

Theme, font and size, cursor style and blink, and sidebar row density. See Appearance & terminal for what each one does.

Terminal

Default shell, the directory new sessions start in, scrollback length, the bell (off, audible or visual), copy on selection, and whether Option sends Meta.

The rest decide what happens around a session rather than inside it: closing one that is still running can ask first, a session can close itself when Claude exits, sessions can come back on launch, and the conversations they were having can be resumed with them. The ⌃⌥⌘↩ summon is here too, and can be switched off.

Scrollback and cursor style apply to new sessions.

Sidebar

Float sessions needing you to the top and Show resource status bar, both off by default.

Sidebar rows

Every part of a session’s row, on up to five lines. Drag a part to another line, or onto Hidden to leave it out; drag a line by its label to move it with everything on it. Right-clicking a part or a line does the same from a menu, and a sample row above the editor shows the result as you drag.

• Title — the session’s name, and the one part that cannot be hidden
• Agent — which agent is running, shown once more than one is set up
• Status — Working, Your turn, Needs permission, Question, Plan ready, or a failed turn or a stall
• Detail — what the agent is doing. On the status’s line it takes the label’s place while the session works; on a line of its own it also shows what a finished turn was last doing, or what a prompt is asking about
• Time Waiting — how long the session has been waiting on you
• Branch — the git branch the session is on
• Model — the model in use
• Context % — context window used, coloured green under 70%, amber under 90%, red above
• Mode — the permission mode, when it is not the default
• Subagents — how many subagents are running

A part with nothing to show takes no room, and a line with nothing on it disappears. By default the agent badge leads the title, the status shares a line with its detail and waiting time, the branch has a line to itself, and the model, context, mode and subagent chips go underneath. Reset to Default puts that back.

Model label decides how much of the name the model chip spells out:

Style	Chip
Initials	O5
Family	Opus
Family and version	Opus 5
Full name	Opus 5 (1M context)
Model ID	claude-opus-5[1m]

Opus 5 is the default.

Notifications

A switch per state, sounds, and the Dock bounce. See Notifications & attention.

If macOS is blocking or swallowing Fleet’s banners, this pane says so above the switches.

Activity & detection

Session activity subtitles, on by default, and Mark stalled after — how long a session can report Working with no terminal output before Fleet flags it. See AI enhancements.

Updates

Fleet checks for a new version shortly after launch and every few hours after that. This pane shows the version you are on and what the updater is doing, and Check Now is here as well as in the Fleet menu.

Every session in Fleet is a live shell, so Fleet never restarts itself to install. A new version is downloaded, verified and staged in the background, and with Update without quitting on, which is the default, your sessions move to it while they run. The new version launches and is handed every terminal, with its screen and scrollback and the layout around them, and the old one steps aside. The two copies of Fleet pass them over a local socket; none of it is written to disk or sent over the network.

That starts on its own once nobody has typed into Fleet for a minute, or at Update Now on the sidebar banner or the menu-bar extra. The automatic start also waits while Fleet itself holds something typed that would not survive the move: a character still being composed, the command palette, Quick Switcher, search or welcome guide open, a sheet or alert, or text in a field. Later hides the banner and holds the move for four hours; Update Now or checking for updates ends that early, and quitting still installs.

The new version runs on trial for two minutes. If it crashes, stops responding, stops reading a terminal, or never confirms it has the sessions, the old version takes every session back and puts its own app back in place. That version is then listed here under Rolled back and is not installed again, even when checked for by hand, until you click Allow Again; Report… beside it opens an issue about it in your browser. A later release is offered as usual.

With Update without quitting off, a staged update installs the next time you quit instead, and Restart Now is offered if you would rather not wait, which closes every running session. With Download and install them automatically off, Fleet says a new version exists and leaves it to you; one you download from the banner installs the same way as any other. You can also turn off automatic checks altogether.

New versions reach installs in stages. When a check finds a newer version, Fleet also reads the rollout schedule published beside it, and takes the version only once the current stage covers this Mac. Where this Mac falls is a number from 0 to 9999, drawn once, kept in config.json as updateRolloutBucket and never sent. A version whose rollout has been paused is not installed. Checking by hand skips the stages, but never a pause. Checks carry on after an update is staged, and a newer release replaces the staged one.

Privacy

Anonymous usage and crash reporting, on by default. Fleet reports which features get used, counts in coarse bands rather than exact numbers, and the crash reports macOS collects.

It never sends terminal output, session titles, working directories, git branches, AI summaries, file paths or anything you type — the event format has no way to carry text at all.

Share anonymous usage & crash reports turns it off. The install ID is random, not tied to you or your Mac, and replaced with a new one every day; switching the toggle off deletes it, along with anything not yet sent.

DO_NOT_TRACK=1 — or FLEET_NO_TELEMETRY=1 — in Fleet’s environment switches it off for that launch without touching the setting. An app started from the Dock reads its environment from launchctl setenv or open --env, not from your shell profile.

The privacy policy lists everything reporting can send, and where it goes.

Permissions

macOS asks about Desktop, Documents and Downloads separately, the first time something reads one — so in a terminal they arrive scattered across whatever you happened to be doing. They cannot be combined into a single prompt, but this pane will walk all three now, one at a time.

macOS will not ask a second time about anything you denied. Files & Folders in System Settings is the only place that can change that answer, and the pane links straight to it.

Full Disk Access covers every protected folder at once, including the shells Fleet starts for you — the shortcut if you would rather not be asked at all. Fleet cannot grant it; the switch lives in System Settings.

Agent integrations

A section for each agent found on your Mac: Claude Code, Codex, Antigravity. Each installs that agent’s copy of the fleet plugin, reports whether it is working, and repairs it. The Claude Code section also lists the config directories Fleet keeps up to date, and holds the two switches that let a session drive Fleet. See AI enhancements and Driving Fleet from an agent.

Re-running onboarding

Set onboardingSeen to false in config.json, or use Help → Welcome to Fleet.