Core concepts

Plexus nests your work in a three-tier hierarchy and gives every session two independent status indicators — learn both and you can navigate the whole app.

The hierarchy

Everything lives in the same order, outermost to innermost, and you see it in the left sidebar tree: expand a workspace to reveal its projects, expand a project to reveal its sessions.

Workspace

A workspace is a named bucket for grouping projects — one per client, team, or area of your work. There is always exactly one default workspace, marked with a star and auto-selected on launch. On first run Plexus creates a Default workspace, so the tree is never empty.

Grouping related projects is also where shared configuration pays off: both settings and hooks cascade Global → Workspace → Project, so a workspace is the natural place to set defaults once for similar repos — a common Create hook that installs dependencies, the files copied into each new worktree, auto-start behavior — and let every project inside inherit them, overriding only where one repo differs.

Project

A project is exactly one git repository registered with Plexus. Adding a project points Plexus at a folder on disk; if it isn't a git repo yet, Plexus offers to run git init for you. Clicking a project's row in the sidebar opens the project view — a Dashboard tab listing the project's sessions and a Git tab with a full git client on the repository's main checkout. Removing a project tears down its sessions but leaves the repository on disk untouched.

You can also archive a whole project from its ⋯ menu — the project and all of its sessions disappear from the tree but stay restorable, the same way archiving works for a single session. When you archive, Plexus stops every session's agent and asks one question: keep each session's worktree on disk (so a restore is instant and sessions stay resumable), or tear down worktrees to reclaim disk — running each session's teardown hooks and removing its worktree, optionally with its branch. Either way the project's settings and hooks are preserved. Archived projects live in the Archived drawer (the button at the bottom of the sidebar), where you can Restore one or delete it permanently. Your git repository on disk is never touched.

Session

A session is the unit of work — think one session = one feature. When you start one, Plexus cuts a dedicated git worktree off a base branch you choose, on its own plexus/<name> branch, and launches a named Claude Code conversation inside it. Because each session has its own worktree, sessions in the same project run in parallel without stepping on each other's files.

Not every task needs a whole worktree, though. When you just want a quick edit or review, choose Start session on root tree to run a session directly in the project's root working tree — no base-branch picker and no isolation, so it launches immediately. Reach for it for fast, throwaway work, and use a standard session when you want the change isolated. See Sessions & worktrees for the full lifecycle and base-branch options.

The two status indicators

Every session row in the tree and the dashboard carries two indicators that are orthogonal — they answer different questions and change independently. A session can be idle with an open (green) PR, or working with no PR yet, in any combination.

Activity

A small dot shows what the agent is doing right now:

• Working — emerald, pulsing. The agent is actively processing a turn.
• Waiting — amber. The agent needs your input or approval.
• Idle — gray. Nothing in flight.

Plexus tracks this automatically through activity hooks installed into each session. See Session status for details, including how to reset a stuck dot.

Branch / PR state

A branch icon shows where the work stands in the pull-request lifecycle:

• Gray — no pull request yet.
• Green — an open pull request exists.
• Purple — the pull request has been merged.

In the dashboard, click the PR icon to open the pull request in your browser. Plexus supports GitHub and Bitbucket — see Connections.

Warm sessions

Switching between sessions is instant because Plexus keeps recently-used sessions warm — their terminal and agent process stay live in the background even while you're looking at another session. A capped number stay warm at once (default 8); exceed the cap and the least-recently-used session is quietly cooled. A cooled session isn't gone — its worktree and conversation are preserved, and switching back resumes it automatically.

That cap is the session.maxWarm setting, so you can tune it to your hardware: raise it on a powerful machine to keep more sessions instant, or lower it on a modest one to save memory — each warm session keeps a live agent and terminal process resident. Set it to 0 for no limit. Adjust it in Settings. See Architecture for how warm sessions work under the hood.