Status & notifications

Every session row carries two indicators — an activity dot, which grows a blue ring when the agent has background work running, and a branch/PR icon — so you can tell at a glance what the agent is doing and where its branch stands.

The activity dot

A colored dot sits next to each session and tracks what the session's own agent is doing right now:

• Working — emerald, with a live pulse. The agent is mid-turn: thinking, running tools, editing files.
• Waiting — amber. The turn finished, or the agent is paused on you — a question, a permission prompt, or a plan waiting for your approval. It's your turn.
• Idle — gray. The session is stopped, or running with nothing in flight.

Every session is in exactly one of those three states, and the dot is about the main agent only. Work it handed to subagents and left running is a separate indicator — see Background subagents below.

The dot is driven by Claude Code's own lifecycle events, bridged back over a private loopback channel — so it follows what the agent is really doing rather than guessing. When a session starts, Plexus installs a small set of activity hooks into the session's working directory. The dot flips to waiting the instant a turn ends, and also when the agent pauses for a plan approval or a multiple-choice question — so a session that needs you never sits there looking busy.

Only the session's own agent moves its dot. Opening another claude in the same folder — in the built-in terminal, an outside shell, or one the agent spawns itself — won't repaint a working session's status. And the dot self-heals: if it reads idle while the agent is demonstrably paused on a plan or question, Plexus flips it to waiting within a couple of seconds; if it reads idle mid-task, it flips back to working as soon as the agent's transcript shows fresh activity.

Background subagents

When the agent hands work to subagents and carries on without waiting for them, a blue pulsing ring appears around the activity dot. The ring is a second, independent signal, so it combines with all three dot colors:

Hover the dot for the count: "Agent working — 3 subagents running".

At Normal density, where a session row names the state in words on its second line, those last two rows say Delegating in blue rather than Needs you or Idle — the main agent isn't mid-turn, and the delegated work is what's still running. The context bar says the same for the session you have open. A session whose agent is mid-turn keeps saying Working, ring or no ring.

The word is about the main agent being free, not about nothing being asked of you. A turn that hands work off and then stops on a question, a permission prompt or a plan waiting for approval also reads Delegating while the ring is lit. The dot is how you tell the two apart: it stays amber, and hovering it says "Waiting for input — 2 subagents running".

You also see it where individual sessions aren't on screen: a collapsed project row shows how many of its sessions are delegating, the workspace switcher in the app bar shows the same for the workspace you're in (and its menu shows it per workspace), and a session's second line in ⌘K search says it in words — Delegating · 2, or Working · 2 delegating when the agent is mid-turn alongside them.

Which agents light the ring

• Background subagents do — work the agent handed off and carried on without waiting for. That includes a batch started by a workflow, which fans work out to several agents running in parallel.
• Foreground subagents don't. A subagent the agent is sitting and waiting on isn't something running beside it — it is the agent working, so the session shows a plain emerald working dot and no ring.
• Other background work doesn't. A shell command the agent left running in the background, and other kinds of background task, aren't subagents.

The ring is worked out from several signals at once. Only a launch can turn it on, and every other signal can only turn it off — so it can't be left lit over work that has already finished:

• Claude Code tells Plexus the instant the agent hands work off, so the ring appears as the work starts. This is also what covers the case that used to hide it altogether: a turn that delegates and stops to ask you a question or show you a plan.
• Plexus also reads the session's own conversation record every couple of seconds, as a check that doesn't depend on anything being reported to it.
• Work started by a workflow is followed through the workflow's own run, which is the only place its individual agents are recorded — so a fan-out lights the ring and each agent drops off it as it finishes.
• Claude Code reports the work it still has in flight, both when the agent's turn ends and each time an individual subagent finishes. That report is the authority in both directions — a subagent that has finished drops off the ring immediately.
• Each running subagent is watched for progress of its own. One that has gone quiet for 30 minutes is dropped, which covers work whose ending was never recorded anywhere — the CLI was killed, or the conversation was cleared mid-delegation.
• Stopping the session, the agent exiting on its own, archiving its project, quitting Plexus, or resetting the session's status (see below) clears the ring straight away.

The branch / PR icon

A second icon shows the git state of the session's branch, color-coded by pull request status:

Hover the icon for details, including the aggregate CI status (pending / passing / failing) for the PR's head commit. When the icon is green or purple, click it to open the pull request in your browser.

Plexus refreshes PR status automatically — when you focus the window, on a periodic poll, and whenever the agent finishes a turn — so the color stays current as a review progresses. See Pull requests for creating and managing PRs, and Connections to connect GitHub or Bitbucket.

Getting notified

When a session moves to waiting, Plexus can alert you even if its window is minimized or you're focused on another session.

Background subagents don't change that. While delegated work is still running, a session that goes amber stays quiet — the work isn't finished, so this isn't the moment the session is done with. That holds whether the turn simply ended or the agent paused to ask you something, which is why the row says Delegating and the dot is what tells you which of the two it is. The alert waits for the real finish: the moment the delegated work drains and the session settles on waiting, you're told once.

Desktop notifications

A native OS notification names the session and what it needs. Controlled by Desktop notifications (Settings → General), which is on by default. On Linux, pop-ups use notify-send when available — install it if notifications don't appear.

Sound

An optional brief two-note chime plays when a session needs input. It's synthesized in memory — no audio files. Controlled by Notification sound (Settings → General), which is off by default; a preview button lets you play the chime and confirm your audio works.

Prefer your own sound? Set a custom sound under global Settings → General. Plexus copies the file you pick into its own data folder, so it stays on your machine and keeps working even if you move or delete the original — and the Notification sound toggle still decides whether it plays. See the Settings reference.

Both settings are session-scoped, so you can tune which sessions are allowed to interrupt you. Toggle them under Settings → General — see the Settings reference.

Resetting a stuck activity dot

Because the dot follows Claude Code's hooks, it can occasionally stick on the wrong state. The usual cause is pressing Esc to interrupt a turn — Claude Code fires no hook for that, so the dot keeps its previous value.

To clear it, open the session's ⋯ menu and choose to reset its status. The dot flips to idle (gray) immediately, and the subagent ring — which can stick the same way, if a subagent's ending was never recorded — clears with it. This only changes the visual indicators — it doesn't touch Claude's actual session or conversation, and it doesn't stop any subagent that is genuinely still running.

A reset on a genuinely stuck dot sticks. If you reset a session whose agent is actually still busy, the self-healing described above kicks in: the dot returns to working or waiting once the agent's activity proves the reset was premature — so a mistaken reset can't hide a live agent.

If the activity dot doesn't move

A dot that stays gray no matter what the agent does is a different problem from one stuck on the wrong colour: something in the chain between Claude Code and Plexus isn't connected. Open the session's ⋯ menu and choose Check activity hooks… — it runs a one-click diagnosis and tells you, in a sentence, which link is broken.

It checks four things:

• What's installed. The hooks Plexus wrote into this session's working directory, and what address they report to.
• Whether that address is still current. Plexus picks a fresh address every time it starts, so a session left running from an earlier launch reports to somewhere that no longer exists. The fix is restarting the session, and the check says so.
• Whether Plexus is reachable. It sends itself a test message. No answer means something on your machine is blocking local connections — a firewall, security software, or a VPN that captures loopback traffic.
• Whether Claude Code actually ran the hooks. Claude Code records what it ran at the end of every turn, so this is answered from the conversation you already had — you don't have to reproduce anything.

Copy report puts the whole thing on your clipboard, ready to paste into a bug report. It carries no secrets of Plexus's: connection tokens appear only as short fingerprints, and hooks you added yourself are counted but never quoted.

The one exception is the hook errors the check shows when the last turn had any. Claude Code reports those for the whole turn rather than per hook, so if one of your own hooks failed, its command line and its output appear alongside Plexus's — and that is where an API key or a password of yours can end up. Plexus blanks out the shapes it recognises, but it can't recognise everything a hook might print, so the errors stay on screen and are left out of the copied report unless you turn on Include these in Copy report underneath them. The report still says how many there were, so nobody reads it as "no errors".