Sesh Docs
sesh.codes
Reference › Settings 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
Show floating chipA bubble in a corner of the screen, over every app, that counts what's working and opens into an approval or question when one comes. Always, When Something Needs You, or Never.
Default AlwaysMac
Answer approvals in the chipAllow and Don't Allow in the floating chip. Off, it only tells you something is waiting.
Default OnMac
Hide while Sesh is in frontHides the floating chip while you're using Sesh itself.
Default OnMac
Hide from screen sharing and recordingsKeeps the floating chip on your screen but out of screen shares, recordings and screenshots.
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
Sesh Tools for AgentsGives agents on that machine Sesh's tools: ask you questions, send you notifications, make artifacts, rename their session.
Default OnMaciPhone & iPad
Let Agents Manage SessionsLets agents on that machine start, message and stop other sessions. Needs Sesh Tools for Agents.
Default OnMaciPhone & iPad

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
Questions from agentsAn agent asked you something and is waiting for the answer.
Default OnMaciPhone & iPadiCloud
Finished turnsAn agent finished and is waiting for you.
Default OnMaciPhone & iPadiCloud
ErrorsA session stopped with an error.
Default OnMaciPhone & iPadiCloud
Agent messagesA note an agent wrote you, like "Tests pass" when you asked to hear.
Default OnMaciPhone & iPadiCloud
Live ActivityWorking sessions and what needs you, on the Lock Screen and in the Dynamic Island, with Allow and Don't Allow for an approval.
Default OniPhone & iPad

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 colorsThe chat, Changes and the sidebar take the theme's backgrounds, and buttons, selection and links its accent.
Default OnMaciPhone & iPadiCloud
App IconThe default icon, or one in a built-in theme's colors. It doesn't change with the theme.
Default DefaultiPhone & iPad
My ThemesThemes you made or imported. New Theme copies one of yours to edit.
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
RepeatMakes the sheet New Routine: the machine runs the task on this schedule, even with Sesh closed. Never, Every Hour, Every Day, Weekdays, Every Week or Custom….
Default NeverMac
RunStarts the task 2, 3 or 4 times, or once per item in a list, each session on its own branch.
Default OnceMac
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 the session's variables: SESH_SESSION_ID, SESH_SESSION_NAME, SESH_BRANCH, SESH_ROOT_PATH, SESH_WORKTREE_PATH and SESH_SESSION_PORT.
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/
teardownShell command run in a session's copy of the project before it's deleted, like docker compose down. If it fails, the session is still deleted and Sesh says so. Stopped after 2 minutes.
Default None
teardownOnArchiveAlso run teardown when a session is archived. Setup and session setup run again before its agent next starts.
Default false
sessionSetupShell command run in every new session's copy of the project after setup, even when setup was skipped for a prepared copy. For what's different in each session, like writing SESH_SESSION_PORT into .env.local.
Default None
preparedCopyNew sessions start from a copy of a session folder setup already ran in, and skip setup unless lockfiles changed. false runs setup every time. Setup that uses a session's own variables never uses a copy.
Default true
setupInputsMore files (globs) whose changes mean setup runs again on a prepared copy, besides lockfiles and .sesh/.
Default None
portsHow many ports each session gets for its servers: SESH_SESSION_PORT, then SESH_SESSION_PORT_1 and on. No two live sessions on a machine share one. 0 for none.
Default 1
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
--port PORTThe port seshd listens on, for this machine. Other devices reach it by its ID, from any network.
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_PORT_RANGEWhere sessions' ports (SESH_SESSION_PORT) come from, as low-high.
Default 20000-24999Each 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 the machine's ID and a pairing code that works once, for 10 minutes, with a sesh://pair link and a QR code to scan.
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 version, ID, agents and disk space.
Default —Each machine
sesh list · new · send · log · stopList sessions, start one with a prompt, send it a message, follow it, or stop it. Add --id ID (and --token, or --pair CODE the first time) for another machine.
Default —Each machine

Installer

Variables for install.sh

SESH_INSTALL_DIRWhere seshd and sesh are installed.
Default ~/.local/binEach machine
SESH_NO_SERVICE=1Install the commands only, without starting seshd as a service.
Default UnsetEach machine