Your first session

This page takes you from a fresh install to an agent working on its own branch, and shows you what’s on screen while it works.

Run spwn

spwn

spwn starts its server on 127.0.0.1:4317 and opens the UI in your browser. Leave the terminal running; closing it stops the server. Your agents and shells keep running in rmux panes, though, and reattach the next time you start spwn.

First-run setup

When spwn has no projects yet, it opens a three-step setup screen. Every step can be skipped, and Skip setup closes it for good in this browser.

1. Sign in. spwn checks whether the claude CLI is installed and signed in. If it isn’t signed in, Sign in to Claude opens a terminal right there and runs claude; follow its prompts (a URL to open, a code to paste back). The screen moves on by itself once you’re signed in. If spwn can’t find claude at all, install it or set its path in Settings → Agents.
2. GitHub (optional). Paste a GitHub token if you want to clone, pull and push private repositories or open pull requests. spwn hands it to git and gh in your shells and agents. Public repositories need nothing.
3. First repo. Clone something to work on (see below), or skip this and add a folder you already have.

Tip

On a server with ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN in its environment, spwn treats Claude as signed in and step 1 is already done. claude uses the key; spwn only checks that it is set.

Add a project

A project is a name and a folder. Its sessions branch from whatever that folder’s repository has checked out. The top of the sidebar has two ways in:

• ＋ New Project opens a folder browser over the machine spwn is running on. Pick a folder and it becomes a project named after it.
• ⎇ Clone repo takes owner/repo or a full GitHub URL and a parent folder (default ~/code, created if missing). spwn clones into <parent>/<repo-name> and adds the clone as a project.

A project should be a git repository. That is what gives each session its own worktree and branch; in a plain folder, sessions run in the folder itself.

Start a session

Expand the project in the sidebar and click ＋ New session. spwn:

1. creates a git worktree on a new spwn/<id> branch, off the branch the project has checked out,
2. runs the project’s session-created hooks,
3. starts claude in that worktree, in an rmux pane.

Type your first prompt into the agent’s terminal as you normally would. With more than one agent installed, the project’s ⋯ menu offers New agent session for each.

What you see

The sidebar

The Fleet sits at the top, with a badge counting sessions that need you. Under each project:

• Merge tray, Scheduled Tasks, Land order, Workflows and, for a git repo, Source Control.
• Your shells, marked $.
• Your sessions, marked ✦. A fork nests under the session it came from, marked ↳, so the list reads as a tree.

Each session row carries chips and a status mark:

Mark	Meaning
⎇ <branch>	The session’s git branch.
⇄	A workflow created it.
↑3	Commits on the branch that aren’t in its base.
⚠2	Files that would conflict with the base.
◑1	Other sessions changing the same files.
$0.42	Spend so far (see cost tracking).
spinner	Working on a turn.
pulsing amber dot, yellow title	Waiting for you: a permission prompt or a question.
steady amber dot	Turn finished, and you haven’t looked yet.
green dot	Ready to land.
red dot, red title	An error, a failed hook, or a sync that stopped on conflicts.

A session you’re looking at never shows an attention dot. Rows hold ⑂ (fork), </> (open the editor) and × (delete). Deleting a session removes its worktree and its branch, and the confirm dialog names any unmerged work first.

The agent pane

Opening a session shows the agent’s real TUI, live. Keystrokes go straight to it, so permission prompts, questions and slash commands work exactly as they do in a terminal. Around it:

• The status strip along the top: where the code lives, the branch, how far ahead of its base it is, whether it has uncommitted work, and the last hook result. Click it to open the Inspector.
• The agent bar: the agent’s name, the spend chip, Ask / Accept edits / Plan to switch permission mode, Stop to interrupt the turn, and Transcript.
• The Inspector, a side panel with tabs: Overview (branch, changed files, lineage, merge), Diff, PR (the session’s PR doc and spend), Transcript, Timeline and Hooks.

The Transcript tab mirrors the conversation as chat, rendered from the session’s own transcript on disk. It’s where the per-turn actions live that a terminal has nowhere to put: fork from this turn, rewind to it, or add it to the Merge tray. ⌘F searches it.

Every finished turn is committed on the session branch, so there’s never anything to reconstruct at the end.

Shells

A shell is a plain terminal with no worktree and no conversation. Open one from a project’s ⋯ menu (New shell) or the command palette (⌘K, then New shell in …). It starts in the project’s folder, and like agent panes it survives a restart of spwn.

Where next

• Cost tracking: what each session and each problem costs, counted from the transcripts.
• Sessions & worktrees: how branches, forks and merging work.
• Hooks: run your own scripts when a session is created, finishes a turn, or is deleted.