Sessions & worktrees

A session is one named Claude Code agent running in its own git worktree, on a branch it either cuts for you or checks out — the atomic unit of work in Plexus.

Creating a session

Open the ⋯ menu on a project row in the tree and choose New session, or press the + in the app bar. Give it a name (required), then pick how the session gets its branch — New branch, the default, or Existing branch — fill in that mode's fields, and click Create.

Which project it lands in

Project is the dialog's own field, prefilled from wherever you opened it: the row you used, or — from the app bar's + — the project you have open. Change it there rather than closing the dialog and starting again.

It offers the same projects the sidebar shows: the current workspace's, or every workspace's grouped by name if you have set Workspace navigation to "All workspaces in the sidebar" (see Settings). If the dialog was opened on a project in another workspace — from a dashboard row, say — both workspaces are listed under their names, so you can still get back.

Switching project re-reads that repository's branches, so the base branch and any branch you had picked are cleared — a branch name means nothing in a different repository. The name you typed is kept; a name Plexus filled in for you from a branch is not.

Whichever mode you use, the rest of the session is identical: the same worktree location, the same create, run, and teardown hooks, and the same Agent, Review, Explorer, and Git tabs.

Two sessions in the same project can share a display name; it's the branch that has to be unique. In New branch mode Plexus guarantees that with a suffix, and in Existing branch mode git does — a branch can only be checked out in one worktree at a time.

New branch

The default, and the classic Plexus flow. Pick a base branch — Plexus preselects the branch currently checked out in the project's main working copy (or a fixed default you pin per project with the Default base branch setting in Settings → Worktrees & Hooks) and lists both local and remote branches.

When the session starts, Plexus cuts a fresh git worktree, branches a new plexus/<name> branch off the base (deduplicated if that name is taken), and mints a named Claude Code conversation inside it. The session owns that branch for its lifetime, so any number of sessions per project run independently without stepping on each other's files.

Existing branch

Switch the dialog to Existing branch when the branch already exists — to carry on a branch a colleague pushed, or to spin a session up purely to review one. There are two fields:

• Branch — the branch to check out into the session's worktree. Branches that exist only on your remote are listed alongside local ones.
• Compare with — the base the session is measured against. It defaults to the repository's trunk (whatever origin/HEAD points at — usually main), not to the branch checked out in your main working copy, because a branch you didn't cut from that checkout has no particular relationship to it.

The base is never checked out by the session; it is the ref everything compares against. The Review tab diffs the branch against it, Rebase onto… in the Git tab targets it, and a pull request opened from the session uses it as its base — so pick the branch you intend to merge into. A project's Default base branch setting overrides the default in both modes.

Plexus creates the worktree and checks the branch out into it; it does not create, rename, or move the branch itself.

Some branches can't be picked. git allows a branch to be checked out in exactly one worktree at a time, so a branch that's already checked out somewhere is still listed, but unavailable — with the reason:

• another session has it — open that session, or remove it first;
• your project's own working copy is on it — switch that checkout to another branch;
• a worktree that no longer exists still holds git's record of it — clear that one with Prune stale worktree entries… in the project Git tab.

A branch that lives only on the remote becomes a real local branch tracking origin/<name>, rather than a detached snapshot. The session starts at the remote's tip, and ahead/behind counts, Push, and pull requests all behave exactly as they would on a branch you created yourself.

Pull before you start

The worktree is cut from your local copy of the branch it starts from. Background fetching keeps Plexus's picture of the remote current, but it never moves your own branches — so if your local main is a few days behind, a new session off main starts a few days behind too, and you find out at pull-request time. The same goes for an existing branch that's been pushed to since you last pulled it.

One toggle in the New session dialog closes that gap, and it follows the mode you're in:

• In New branch mode it reads Pull base branch first and fetches, then fast-forwards, the base before the session is created.
• In Existing branch mode it reads Pull the branch first and does the same for the branch you picked, so the worktree starts at the remote's tip instead of your older copy. The base is left alone.

Plexus remembers the toggle for next time. It does nothing when there's nothing to pull — a branch with no remote copy, one that's already current, or one that is merely ahead of the remote because you have commits you haven't pushed yet. That last case is left alone deliberately: there's nothing to catch up on, so the session is created normally.

Picking a branch from the Remote branches group is the same story from the other side: you have no local copy of it yet, so the fetch is the whole job — Plexus creates your local branch from the freshly fetched remote one, which is already at the remote's tip. The toggle simply makes sure that fetch is fresh.

Start session on root tree

When you just want a quick edit or review without a separate worktree, open the project's ⋯ menu and choose Start session on root tree. There's no base-branch picker — the session runs directly in the project's root working tree and launches immediately. Because root-tree sessions share that one working directory, use them for fast, throwaway work and reach for a standard session when you want isolation. More on layout in Worktrees & environment.

Lifecycle

A session is just metadata until you start it. The agent process is killed when you stop it, but the worktree, branch, and conversation persist — so a stopped session is always resumable.

By default a standard session launches the moment it's created — Start new sessions automatically (Settings → Agent) defaults to on. Turn it off (project, workspace, or global scope) to have new sessions wait for you to click Start. Root-tree sessions always launch on create.

Start, stop, resume

Select a session and click Start in the Agent tab. A Starting… spinner shows the live stage — Creating worktree…, Running <hook>…, then Starting agent… — before the terminal takes over. Click Stop to end the agent; if Claude Code exits on its own (you run /exit, or it crashes), the session drops to stopped automatically.

Cancel sits under the spinner from the moment a start begins, so you are never stuck watching it. Cancelling stops whatever step is in flight and cleans up after it — the half-created worktree is removed, and the session returns to Start / Resume. The branch goes with it only if Plexus cut it: a branch that already existed before the session is left exactly as it was. That rule holds for every way a start can fall over — a cancel, a create hook that aborts the launch, or an agent that fails to spawn — so Plexus never deletes a branch it didn't create without asking. A session running on the project's own checkout has no separate worktree, and cancelling one never touches your repository.

If a start goes quiet for a minute, Plexus says so and offers Stop as well. It does not give up on its own: the first checkout of a large repository can legitimately take a while, so the decision stays yours. The elapsed time is shown so you can judge it.

Click Resume to restart a stopped session. Plexus verifies the worktree still exists, re-runs your run hooks, and reattaches the same conversation — your prior transcript and context are intact.

The colored dot on each tree row tells you what needs you — working, waiting, or idle. See Status & indicators for the full breakdown.

Session summary

Every session's context bar carries a Summary button, next to Close session. It opens a panel beside the tabs holding an AI-written recap of that session: a one-line What was asked, then a short What's been done list of the concrete progress and where things stand. It is the quickest way back into a session you left an hour ago — or into whichever of five running sessions you switch to next.

The panel refreshes itself each time the agent stops, provided you have that session open with the panel showing: a session working in the background never spends a turn on a summary nobody is watching, and catches up the moment you come back to it. The refresh button in the panel's header regenerates it on demand. A refresh that finds the transcript unchanged does nothing at all, and an ordinary one sends only the turns since the last summary rather than the whole conversation. The summary is stored with the session, so it survives quitting Plexus and is on screen the instant you reopen the panel.

Turning it on

Summaries are off until you ask for them, because each one spends a turn. Open the panel on any session and it says exactly that, and offers two ways to switch them on:

• Turn on for <project> — this project only, and every session in it. That is the narrowest scope the setting has; there is no per-session version.
• Turn on everywhere — the global default, for every project.

Either button writes the AI session summary setting at that layer and then generates the first summary straight away, instead of leaving you waiting for the agent's next stop. Nothing is read from the session's transcript until you press one: while the feature is off, the panel only describes it.

Model for session summaries decides which model writes it — Haiku by default, so a summary lands quickly. Both settings sit under Settings → Agent and can be set globally or overridden per workspace or project; see Settings, which is also where you switch summaries back off.

Archive vs. remove

Plexus gives you two ways to retire a session, and they are not the same. Reach both from the per-row ⋯ menu.

Removal is idempotent: if a teardown hook fails, or the worktree was already deleted out of band, removal still completes. It also clears git's own record of the worktree, not just the folder — otherwise git would keep treating the session's branch as checked out somewhere and refuse to delete or check it out. A worktree that genuinely can't be removed — something is still holding its files — is reported rather than silently skipped, so it never disappears from view while it's still on disk. If you asked for the branch to go too and git kept it — another worktree still has it checked out — Plexus says so instead of reporting a clean removal, so you can delete it from the project's Git tab. Root-tree sessions have no separate worktree, so removing them skips worktree removal.

Deleting the branch of a session that cut its own plexus/… branch is the ordinary case, and it's forceful: that branch existed only for the session, so it goes even if it still carries commits. A session started on an existing branch is treated differently, because that branch outlives the session and may be someone else's:

• The branch checkbox in the removal dialog starts off, and stays off — Plexus never pre-ticks it from what you chose last time.
• Ticking it brings a second confirmation naming the branch, so deleting it is always a deliberate, specific act.
• The deletion itself is the safe kind (git branch -d). A branch still carrying commits that are merged nowhere else is kept, and reported as kept rather than quietly skipped. If you really do want it gone, delete it from the project Git tab, which offers the forceful version and spells out that its commits go with it.
• The automatic cleanup after a merge holds the same line without you present: it never deletes a branch that existed before the session, because there is no dialog in which to confirm one.

The Archived drawer — opened from the button at the bottom of the sidebar — lists archived sessions alongside archived projects, each with Restore and permanent-delete actions. You can archive a whole project the same way you archive a session.

Removing a project or a workspace asks the same question the archive dialog does: Tear down worktrees (and optionally their branches), off by default. Leaving it off keeps every worktree on disk — reclaim them later from the Git tab's Worktrees section. These bulk paths can't stop and ask about one branch at a time, so they hold the same line: Also delete branches covers only the plexus/… branches Plexus cut, and a branch a session merely checked out is kept. Taking those too is a third switch, Also delete branches Plexus didn't create, and ticking it asks again — listing exactly which branches it means and which session each belongs to, archived sessions included. Even then the deletion is the safe kind: a branch still carrying unmerged commits is kept, and counted in what the dialog reports as left behind. Either way, the agents running in those sessions are stopped first, and the teardown hooks of every session that was started run: a delete drops the sessions for good, so it's the last chance those hooks get to shut down containers or clean up whatever else they were written for. (Archiving is different — it's restorable, so its keep-the-worktrees path leaves the hooks for the eventual real teardown.)

Teardown mode

The When you remove a session setting (Settings → General) controls what Remove session… actually does:

One other thing follows this setting: the merged-pull-request cleanup. It runs unattended, so it never stops to ask — Ask each time deletes there.