Sessions & worktrees
A session is one named Claude Code agent running in its own git worktree on its own branch — the atomic unit of work in Plexus.
Creating a session
Open the ⋯ menu on a project row in the tree and choose New session. Give it a name (required) and pick a base branch — Plexus preselects a smart default (the repo's default branch, or whatever is currently checked out) and lists both local and remote branches. Click Create.
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.
Two sessions in the same project can share a display name — the underlying branch gets a unique suffix so they never collide.
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.
| Start | Cut the worktree, run create + run hooks, and launch the agent on a fresh branch. |
| Resume | Reattach the same conversation to a stopped session and pick up where it left off. |
| Stop | End the agent process but keep the worktree, branch, and transcript intact. |
| Archive | Hide the session in the archived drawer, fully restorable, nothing removed from disk. |
By default a standard session launches the moment it's created — session.autoStart 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.
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.
Sessions survive closing and reopening Plexus. Live agents don't, so on launch every previously running session is reconciled to stopped — but its pinned conversation id is kept, so the next Resume reattaches exactly as if the app never closed.
The colored dot on each tree row tells you what needs you — working, waiting, or idle. See Status & indicators for the full breakdown.
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.
| Action | What it does | Reversible? |
|---|---|---|
| Archive (soft) | Hides the session in the Archived drawer but keeps its worktree, branch, and transcript. | Yes — unarchive to restore it. |
| Remove (hard) | Runs teardown hooks, removes the worktree and (optionally) its branch, and drops the session row. | No — it's permanent. |
Removal is best-effort and idempotent: if a teardown hook fails, or the worktree or branch was already deleted out of band, removal still completes. Root-tree sessions have no separate worktree, so removing them skips worktree removal.
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.
Teardown mode
The teardownMode setting controls what Remove session… actually does:
| Value | Behavior |
|---|---|
delete | Hard-delete immediately (the default). |
archive | Archive instead of deleting. |
prompt | Ask each time whether to archive or delete. |
With the default teardownMode of delete, removing a session tears down its worktree and deletes its branch (a checkbox in the confirmation, on by default). Switch to archive or prompt in Settings if you want a safer default.