Settings

Settings opens as a tab of its own. A rail down the left splits it into sections, and Save in the header writes everything at once. The exceptions are the GitHub token, desktop notifications, Restore published rates, and the Account controls, which each apply the moment you use them.

Sections

Agents

One card per agent definition: its name, whether its binary was found, the capabilities the definition declares (transcript, status, rewind, scheduled), and a path field.

Control	Key	Default	What it does
Path field on each agent card	agentPaths.<agent-id>	empty (auto-detect)	Where that agent’s CLI binary is. Leave it blank to find it on your PATH, and fill it in only when the binary is somewhere unusual. Browse… picks a file.
Default agent for new sessions	defaultAgent	null (the first installed agent)	Which agent a new session uses when you don’t pick one.
Open ~/.spwn/agents	—	—	Reveals the folder of agent definitions (.toml).
Reload definitions	—	—	Re-reads that folder and reports any file that failed to parse. spwn also watches the folder and reloads on save, so you rarely need this.

Sessions

Control	Key	Default	What it does
Session worktree location	worktreeLocation	"sibling"	Where new session worktrees go. See the table below. Applies to new sessions only. Existing worktrees stay where they were made.
code-server path (session editor)	idePath	null (auto)	The code-server binary for the browser editor. When empty, spwn looks on your PATH, then downloads its own copy the first time you open an editor. Only used for sessions on this machine. A session inside a hook-provided environment needs code-server in that environment’s image.

worktreeLocation	Worktrees go in	Notes
"sibling"	<repo-parent>/.<repo-name>-worktrees/	Outside the working tree, so builds, file watchers and IDE indexers never see them.
"internal"	<repo>/.spwn/worktrees/	Registered in .git/info/exclude. Tools with explicit include globs may still scan them.
"appData"	<app data dir>/worktrees/	Away from your repos entirely.

Notifications

Control	Stored	Default	What it does
Desktop notifications	this browser (localStorage)	Off	Off, When a session needs input, or When a session needs input or has work ready. Turning it on asks the browser for permission. It needs a secure page (https or localhost).

This preference isn’t in settings.json. Browser permission is per browser, so the setting is too.

Model prices

The rate table that turns measured tokens into dollar estimates. See Model prices for the details.

Control	Key	Default	What it does
The price table	modelPrices	Anthropic’s published rates	Model id → { input, output, cacheWrite5m, cacheWrite1h, cacheRead }, in USD per million tokens. Ids match by longest prefix.
Add model…	—	—	Adds a blank row. A row with no model id is dropped on save.
Restore published rates	—	—	Saves immediately with modelPrices absent, which re-seeds the shipped table.
Empty the table	—	—	Clears every row. After Save, no session gets a dollar figure, only tokens. Use this on a Max or Team plan.

Hooks

Control	Key	Default	What it does
Run shared global hooks	globalHooksEnabled	true	Whether the scripts in ~/.spwn/hooks run. Per-repo .spwn/hooks run either way.
Open hooks folder…	—	—	Reveals ~/.spwn/hooks.

Turning global hooks off turns off worktrees

spwn’s own worktree create/remove, per-turn commit and checkpoint ship as default scripts in ~/.spwn/hooks. With global hooks off, new sessions run in the project folder with no worktree or branch of their own, deleting a session no longer removes its worktree, and the per-turn commit and checkpoint stop. See How hooks work.

GitHub

Control	Stored	What it does
Save token / Remove	<app data dir>/github-token, mode 0600	A personal access token that lets spwn, and git and gh inside your sessions, clone, fetch, pull and push private repos over HTTPS. Use a classic token with the repo scope, or a fine-grained one with read and write access to Contents and Pull requests. It saves the moment you press the button. While a token is saved, gh inside a session uses spwn’s config rather than your own gh auth login.

The helper is scoped to https://github.com, so the token is never offered to another host.

Account

On a spwn bound to localhost with no accounts, this section only explains that anything that can reach the port can already act as you. When accounts are on, it shows who you’re signed in as, and offers:

• Password: change it, which signs out your other devices. This isn’t shown when your identity comes from SSO or a proxy.
• Access tokens: tokens for git clone, curl and CI. Use the token as the password, with any username. A new token is shown once.
• Sign out and Sign out everywhere.

Accounts are stored in auth.json in the app data dir, not in settings.json. See Remote access.

About

The running spwn version.

settings.json

Every key above that isn’t marked as stored elsewhere lives in one JSON file:

{
  "agentPaths": { "claude": "/opt/homebrew/bin/claude" },
  "defaultAgent": "claude",
  "worktreeLocation": "sibling",
  "globalHooksEnabled": true,
  "modelPrices": {
    "claude-opus-5": { "input": 5.0, "output": 25.0, "cacheWrite5m": 6.25, "cacheWrite1h": 10.0, "cacheRead": 0.5 }
  },
  "idePath": null
}

Key	Type	Default when absent
agentPaths	object, agent id → path	{} (auto-detect everything)
defaultAgent	string or null	null (the first installed agent)
worktreeLocation	"sibling", "internal" or "appData"	"sibling"
globalHooksEnabled	boolean	true
modelPrices	object, model id → rates	the published rates. {} stays empty.
idePath	string or null	null (PATH, then a downloaded copy)
claudePath	string	Legacy. Moved into agentPaths.claude on load, unless that’s already set.

A few things to know if you edit it by hand:

• spwn reads the file once, at startup. Restart the server after a hand edit.
• Save in the UI writes the whole file from what the page holds, so an edit made while spwn is running is overwritten on the next save.
• If the file doesn’t parse, spwn starts with the defaults.

Where spwn keeps its data

Everything spwn keeps for itself lives in one app data directory, named gg.spwn.spwn under your platform’s data directory:

Platform	App data dir
macOS	~/Library/Application Support/gg.spwn.spwn/
Linux	~/.local/share/gg.spwn.spwn/ (or $XDG_DATA_HOME/gg.spwn.spwn/)

Inside it:

Path	Holds
settings.json	The settings above.
projects.json	Your projects and sessions.
auth.json	Accounts and access tokens, when accounts are on.
github-token	The GitHub token, mode 0600.
gh/	The gh config spwn gives your sessions while a token is saved.
checkpoints/<session-id>/	Copy-on-write code snapshots for rewind.
worktrees/	Session worktrees, with the appData layout.
ide/	The browser editor’s sockets and downloaded code-server.
land-queue.json, pr-cache.json, turns/	spwn’s own bookkeeping.

If you’re upgrading from an install that used an older directory name (com.markbarta.spwn or com.spwn.spwn), spwn moves it into place on first start.

Things that aren’t in the app data dir:

• Agent definitions are in ~/.spwn/agents/, and global hooks are in ~/.spwn/hooks/.
• Per-project configuration is in the repo’s .spwn/: hooks/, workflows/, schedules/, agents/. Session PR docs, including cost, are in .spwn/pr/ on each session’s branch.
• Claude’s own data: spwn reads ~/.claude/projects/ and ~/.claude.json, and never writes to them.