DocsWorking with agents
Sessions & worktrees
A session is a single agent running in its own git worktree on its own branch — the atomic unit of work in Plexus.
What a session is
When you start a session, Plexus creates a worktree, checks out a new branch, and launches an agent inside it. The session owns that branch for its lifetime. You can have many sessions per project, each working independently.
Lifecycle
| Start | Create the worktree and launch the agent on a fresh branch. |
| Resume | Reattach to a paused session and continue where it left off. |
| Stop | Halt the agent but keep the worktree and its changes. |
| Archive | Remove the worktree once the work has merged or been discarded. |
Activity states
Every session shows a colored status dot so you always know what needs you:
- Working — emerald, with a live pulse. The agent is actively running.
- Waiting — amber. The agent needs your input or approval.
- Idle — muted gray. Nothing in flight.
Sort the dashboard by Needs input first to surface every waiting session at the top.
Running in parallel
Because each session is its own worktree, parallelism is safe by construction. Kick off a refactor in one, a bug fix in another, and a docs pass in a third — none of them can step on each other's files.