Sessions & worktrees

A session is one named Claude Code agent running in its own git worktree, on a branch Plexus cuts for you or one that already exists — the unit of work in Plexus, and how several agents run in parallel without their changes colliding.

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.

Every dropdown in the dialog — Project, Template and Base branch — can be searched: open it and type, or start typing while it has focus, then pick a row with the arrow keys and Enter. In a repository with hundreds of branches, a few letters of the name are usually enough.

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.

On top of another session

To build on work another session hasn't merged yet, start the new session on top of it: choose New stacked session… from that session's ⋯ menu, or pick it in the dialog's Stack on field. The base is locked to that session's branch, the new session nests under it in the sidebar, and Plexus keeps it synced as the session below it moves — see Stacks & ordered merging. To put a session that already exists on top of another one, choose Stack on… in its own ⋯ menu. Picking another session's branch as the base by hand works without a plan; the dialog then offers to stack on that session instead.

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.

Only one copy of Plexus runs at a time on your user account. Opening it again while it's already running shows a message saying so and closes the second copy, so your running sessions are left alone rather than being marked stopped by a second start-up. Restarting Plexus to install an update isn't affected: the new copy waits a few seconds for the old one to finish closing.

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

In a window of its own

Open in new window in a session's ⋯ menu, or ⌘⇧N with the session selected, moves the whole session — agent, tabs and scratch terminals — into a separate window, for a second monitor, say. The agent keeps running while it moves. Closing that window brings the session back to the main window. See Multiple windows.

Side by side in a split view

To watch several sessions of the same project at once, put them in a split view: Add to split view ▸ New split view… in a session's ⋯ menu, or New split view… in the project's. The split view gets its own row in the project's session list, with its sessions listed under it, and clicking that row shows them side by side, each pane a full session with its own tabs. Up to six sessions fit in one, and a session is in one split view at most. Archiving or deleting a session takes it out of its split view; restoring it brings it back as an ordinary row at the end of the list. See Split view.

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.

Whatever you ask for, a branch another session is based on is never deleted with its session — the session stacked on it, or any session you started with that branch as its base. Removal goes ahead, the branch stays, and Plexus tells you which session kept it. Removing a whole project or workspace deletes such a branch only when the session based on it is being removed in the same go.

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.

Starting with a prompt

The New session dialog has a Template field once you have saved at least one prompt template. Pick one, fill in its fields, and the rendered prompt is waiting in the terminal when the agent comes up — including when auto-start is off, in which case it waits until you press Start.

Plexus types the prompt in and leaves it there. It never presses return for you.

Save as template… in a session's ⋯ menu does the reverse: it lifts that session's opening prompt into a new template you can edit. It works on a stopped or archived session, which is usually when you know the prompt was worth keeping.

Starting from an issue

When a project has a GitHub repository attached to its toolchain, its Issues tab lists that repository's open issues, and every row has Start session. It opens this same dialog with the name filled in as #123 The issue's title, a Linked to #123 chip under it, and one extra checkbox, on by default — Send the issue to the agent as the first prompt — which types the issue's title, its link and its full text into the agent when it comes up, with a request to reference #123 in its commits. If you also pick a template, the template's prompt goes first and the issue follows it.

The branch is named from the session as always, so it comes out as plexus/123-the-issues-title: the issue number is in the branch because Plexus named it, not because anything read it back afterwards. Rename the session before you press Create and the branch follows the new name; the link to the issue stays either way, because it is written with the session, not read from the branch.

From then on the session's context bar shows a #123 chip that opens the issue sidebar, the issue's row in the Issues tab lists the session, and Create PR starts the description with Closes #123. See Issues for the tab itself, including what a plan gates there.

From a Plnnrly work item

A Plnnrly tab works the same way: every work item has Start session, which fills the name in as OPTH-186 The work item's title, shows a Linked to OPTH-186 · acme.plnnrly.com chip, and offers the same checkbox — the work item's title, its link and its description go to the agent as plain text, with a request to reference OPTH-186 in its commits. The branch comes out as plexus/opth-186-the-work-items-title. The context bar shows an OPTH-186 chip that opens the sidebar below. Create PR adds no Closes line for a work item — that line is for GitHub issues only.

The issue sidebar

A session started from an issue carries the issue with it. An Issue button appears at the right end of the session's tab strip, beside Hook output; press it — or the #123 chip in the context bar — and a sidebar opens on the right with the issue as the Issues tab shows it: the title, the rendered text, labels, assignees, milestone and the comments, all editable, with Open on GitHub in its header. Drag its edge to resize it, press the button again or its × to close it; whether it is open is remembered per session. A session linked to more than one issue gets a switcher at the top of the sidebar. The sidebar needs the same plan the Issues tab does and shows a locked pane without one; the button itself carries no lock.

A session started from a Plnnrly work item gets the same sidebar, named Work item — on the button and in the sidebar's header — with the work item as the Plnnrly tab shows it: its status (with Move to, offering only the moves the project's workflow allows), the description, the side-column fields and the comments, all editable, with Open in Plnnrly in its header. It needs the Plnnrly organization to be connected on this machine; if the Plnnrly project is no longer attached where the session's project can see it, the status and the side-column fields are shown read-only.