Docs › Reference

Settings reference

Every option in Sesh: where it is, what it does, and what it starts as. Settings marked iCloud follow you to your other devices.

General

Settings › General · on iPhone and iPad, Settings › Sessions

Sessions open inChat shows Sesh's transcript, with approvals as buttons. Terminal shows Claude Code's own screen instead; you won't get approval notifications or see when it's working.

Default ChatMaciPhone & iPadiCloud

Open at loginStarts Sesh hidden when you log in, so notifications keep coming. If macOS asks, allow Sesh in System Settings › General › Login Items.

Default OnMac

Show Sesh in the menu barNeeds You, Working and Recent in the menu bar, with Allow and Don't Allow. Keeps Sesh running after you close its window.

Default OnMac

Machines

Settings › Machines

Every computer Sesh runs agents on. This Mac is always first; each row shows Connected, Connecting…, Offline or Needs Update.

Add Machine…Pair another computer by its address, port and a pairing code from sesh pair. Machines you add on one device appear on the others.

Default —MaciPhone & iPadiCloud

Keep Awake While Agents WorkStops that computer from going to sleep while an agent is working. Set per machine, in its ⋯ menu.

Default OnMaciPhone & iPadEach machine

Open TerminalA shell on that machine. In the machine's ⋯ menu.

Default —MaciPhone & iPad

Remove…Removes the machine from Sesh. Its sessions keep running there. Not available for This Mac.

Default —MaciPhone & iPad

UpdateShown when the machine's Sesh service is out of date. Updates and restarts it; sessions carry on.

Default —MaciPhone & iPad

Machine details

Settings › Machines › Details…

AgentsGet, update and remove agents on that machine. Add an Agent… opens the ACP Registry.

Default —MaciPhone & iPad

AccountOn an agent's page: sign in with your account, a device code or an API key, or sign out.

Default Signed outMaciPhone & iPad

VariablesEnvironment variables for every session on that machine, like ANTHROPIC_API_KEY. An API key you enter under Account is saved here.

Default NoneMaciPhone & iPadEach machine

Paired DevicesThe phones, tablets and Macs that can connect to this Mac. Unpair… removes one. This Mac only.

Default —MaciPhone & iPad

Pair iPhone or iPad…Shows a code to scan with Sesh on your phone. Allow Connections appears first if other devices can't reach this Mac yet.

Default —Mac

Dev Servers

Settings › Dev Servers

Open dev servers inWhat the globe button in a session's toolbar does with its localhost: open it in your browser, or in Sesh.

Default Browser on Mac, Sesh on iPhone and iPadMaciPhone & iPad

Notifications

Settings › Notifications

These apply to notifications on this device and to pushes from your machines. Nothing is sent for the session you're looking at. Banner style and sounds are in System Settings › Notifications › Sesh.

Approval requestsAn agent is waiting for you to Allow or Don't Allow.

Default OnMaciPhone & iPadiCloud

Finished turnsAn agent finished and is waiting for you.

Default OnMaciPhone & iPadiCloud

ErrorsA session stopped with an error.

Default OnMaciPhone & iPadiCloud

Theme

Settings › Theme

AppearanceSystem, Light or Dark.

Default SystemMaciPhone & iPadiCloud

Light theme · Dark themeThe VS Code theme for code, terminals and diffs. The one in use follows the appearance.

Default GitHub Light · GitHub DarkMaciPhone & iPadiCloud

Use the theme's backgroundsChat, Changes and the sidebar take the theme's colors.

Default OnMaciPhone & iPadiCloud

Use the theme's accent colorButtons and controls use the theme's accent instead of the system's.

Default OffMaciPhone & iPadiCloud

Match the Dock icon to the themeRecolors Sesh's Dock icon while it runs.

Default OnMac

Import VS Code Theme…Adds a theme from a .json file. It becomes your light or dark theme, whichever it was made for.

Default —MaciPhone & iPad

New Session

File › New Session… (⌘N)

Sesh remembers the machine, project and agent you picked last.

New branchThe session gets its own copy of the project on a new branch. Off works in the project folder itself. Git projects only.

Default OnMaciPhone & iPadiCloud

AutonomousThe agent doesn't ask before acting. Sandboxed where the machine supports it.

Default OffMaciPhone & iPadiCloud

Mode · Model · Effort · FastThe agent's own options, under the task box. Carried over from your last session with that agent, except Mode. They appear once the agent has run on that machine.

Default Last usedMaciPhone & iPad

View

The View menu, and the Changes view

Group ByGroup the sidebar by None, Project or Machine. Also on a section header's right-click menu.

Default NoneMac

Sort BySort the sidebar by Recent Activity, Newest or Name.

Default Recent ActivityMac

File layoutChanged files as a list or a folder tree, in the Changes view.

Default ListMac

Diff styleInline, or side by side, in the Changes view.

Default InlineMac

Project config

.sesh/config.json in the repository

Optional. Without it, Sesh guesses a setup command from your lockfiles and copies .env files into each new session. An empty {} turns the guessing off.

setupShell command run in each new session's copy of the project. It gets SESH_ROOT_PATH, SESH_WORKTREE_PATH, SESH_SESSION_NAME and SESH_BRANCH.

Default Guessed from lockfiles

copyUntracked files to copy into each session, as globs (no **).

Default .env, .env.*

baseBranchThe branch new sessions start from.

Default The remote's default branch

branchPrefixWhat session branch names start with.

Default sesh/

forgeWhere the repository is hosted, for Create Pull Request: { "type", "webURL" }. Types: github, gitlab, bitbucket, azure, gitea, forgejo, codeberg, tangled, sourcehut.

Default Detected from the remote

.sesh/config.json

{
  "setup": "pnpm install",
  "copy": [".env.local", "config/*.local.json"],
  "baseBranch": "develop"
}

seshd

On each machine

The service that runs your agents. The Mac app runs its own; other machines get it from the installer.

seshd installInstalls seshd as a service that starts at login: a LaunchAgent on macOS, a systemd user service on Linux.

Default —Each machine

--host ADDRESSWhere seshd listens. 0.0.0.0 lets other devices connect; 127.0.0.1 is this machine only.

Default 127.0.0.1 (the installer uses 0.0.0.0)Each machine

--port PORTThe port seshd listens on.

Default 4777Each machine

seshd updateUpdates seshd and restarts it. --check only reports whether there's an update.

Default —Each machine

SESH_PROJECTS_DIRWhere Clone Repository… puts projects.

Default ~/codeEach machine

SESH_DATA_DIRWhere seshd keeps its state.

Default ~/Library/Application Support/Sesh, or ~/.local/share/sesh on LinuxEach machine

SESH_LOG_LEVELHow much seshd logs.

Default infoEach machine

sesh

On each machine

Pairs devices and looks after the machine. On a Mac it can also start and follow sessions from the command line.

sesh pairPrints a pairing code that works once, for 10 minutes, and a sesh://pair link.

Default —Each machine

sesh clientsLists the devices paired with this machine.

Default —Each machine

sesh revoke IDUnpairs a device.

Default —Each machine

sesh infoShows the machine's address, port and certificate fingerprint.

Default —Each machine

sesh certificate rotateStarts replacing the machine's certificate. Run sesh certificate finish once your devices have the new one.

Default —Each machine

sesh list · new · send · log · stopList sessions, start one with a prompt, send it a message, follow it, or stop it. macOS only.

Default —Each machine

Installer

Variables for install.sh

SESH_INSTALL_DIRWhere seshd and sesh are installed.

Default ~/.local/binEach machine

SESH_LISTENThe address seshd listens on.

Default 0.0.0.0Each machine

SESH_NO_SERVICE=1Install the commands only, without starting seshd as a service.

Default UnsetEach machine