Core concepts

Plexus organizes your work as Workspace ▸ Project ▸ Session, where each session normally gets its own git worktree and Claude Code conversation, 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.

A workspace can also arrive from somewhere else. If you are in an organization that shares workspaces, one it set up can appear in your sidebar with the organization's name beside it — an ordinary workspace holding the repositories the organization attached, which you can always leave without losing anything under it. See Shared workspaces.

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.

Workspaces and their projects are also the shape cross-device sync carries: turn it on and the same workspaces, in the same order, holding the same projects with the same settings, appear on every machine you sign in on. Sessions and worktrees never travel — those belong to the machine that made them.

Shared workspaces are the exception, and deliberately: they are not part of what sync carries. Each of your machines receives them from the organization directly, so an organization's names and repositories never enter your personal account — and the cost of that is that a settings override you make on one does not follow you. Set a review prompt on an organization's workspace on your desktop and you set it again on your laptop.

A workspace also has a view of its own: click its row and the right pane shows a Dashboard tab — the global dashboard pinned to this workspace — followed by a tab for every tool attached to the workspace's toolchain — a repository's issues, a GitHub project's boards — and a Settings button at the right end of the strip that opens the workspace's settings on its Toolchain page. A tool attached at the workspace is shared with every project inside it by default (each tool has its own switch), which is what makes a workspace of ten services that share one issue tracker a one-time setup — see Toolchain.

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, a Git tab with a full git client on the repository's main checkout, a Terminal tab, and — once a tool is attached to the project's toolchain, or inherited from its workspace — an Issues tab for the repository's GitHub issues, a Board tab for a GitHub project, or a Plnnrly tab for a Plnnrly project. Removing a project tears down its sessions but leaves the repository on disk untouched.

A project can also be one you have on another computer. With cross-device sync on, a project you added elsewhere appears in this machine's sidebar, in the workspace it belongs to, marked Not on this machine. It is a row like any other rather than a warning: the only fact it reports is that a repository you have somewhere else is not checked out here, and it names the repository as well as the project so you can tell two projects called api apart. Locate… points it at the folder if you already have one, Clone… fetches a copy, and Stop showing … here drops the row on this machine alone. If a checkout on this machine already shares a git remote with it, Plexus links the two silently and the row never appears.

A project whose folder has been moved or removed is marked on its row with the path it is looking for, and nothing is deleted — its settings and its sessions are kept, and the row goes back to normal the moment the folder does.

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 for it and launches a named Claude Code conversation inside. By default that worktree gets its own new plexus/<name> branch off a base branch you choose; you can instead point the session at a branch that already exists — local or remote-only — to carry on someone's pushed work or to review 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 Maximum sessions kept ready setting (Settings → General), 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.

The cap never cools a session you can see: with a split view open, every one of its panes counts as in use, including panes hidden behind a maximized one.