Status & notifications

Plexus shows the state of every Claude Code session with two indicators on its row — an activity dot (working, waiting or idle, ringed in blue while background work runs) and a branch/PR icon — plus a state chip when its pull request or its stack has something to say, and can notify you when a session needs your input.

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 you interrupted it, 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 off and left running is a separate indicator — see Background work 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 notifications that actually need you turn the dot amber: a permission prompt, Claude Code's reminder that it is waiting for your input, or a tool asking you to fill something in. Claude Code also sends notices that are just for your information — a background agent finished, a sign-in succeeded, a usage-limit notice — and those leave a working session green.

The dot also follows the two moments Claude Code doesn't announce with an event of its own:

• Pressing Esc to interrupt a turn flips the dot to waiting within a few seconds, instead of leaving it green until your next prompt.
• Approving a permission prompt flips it back to working while the agent carries on, instead of leaving it amber until the turn ends.

To catch those, and anything else a hook missed, Plexus cross-checks the dot every couple of seconds against Claude Code's own record of what the session is doing, and corrects it when the two disagree. Hooks stay the instant signal: the record never overrides something a hook reported more recently. Versions of Claude Code that don't keep that record get the same two corrections from the session's conversation record instead — an interrupt shows up there straight away, and an approved prompt as soon as the agent writes its next output.

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. Forking the conversation from inside the session (/fork or /branch) is different: that is still the session's own agent, so the dot follows it into the fork and keeps updating. 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 work

When the agent hands work off and carries on without waiting for it — to background subagents, a workflow, an agent-team teammate or a cloud session — 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 what's running: "Agent working — 3 subagents running", or "Waiting for input — 1 workflow (4 agents), 2 subagents running · 1 background shell". A workflow is listed once, with the number of its agents still running in brackets. Anything after the middle dot (·) is background work that is running but doesn't light the ring — see Which work lights the ring.

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. Those numbers count background tasks, and a workflow counts as one however many agents it runs.

Which work lights the ring

• Background subagents do — work the agent handed off and carried on without waiting for. Claude Code now runs subagents in the background by default, so most of the agents a session delegates to show up here.
• Workflows do, as one item. A workflow fans work out to several agents, often in phases. The ring stays lit for the whole run — through the gaps between phases, until the last of its agents has finished — and the tooltip shows how many of them are running right now.
• Agent-team teammates and cloud sessions do. They're delegated work running beside the session, the same as a background subagent.
• 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.
• Background shell commands and monitors don't, but the tooltip names them. A dev server or a file watcher the agent left running can run for hours, and a ring lit for all of that time would stop telling you anything — so they're listed after the middle dot instead ("· 1 background shell"). A session with only those running shows no ring, but its tooltip still mentions them.

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 — a background subagent or a workflow — 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.
• 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 — work that has finished drops off the ring immediately. A running workflow is in that report as a single task, which is what keeps the ring lit for the whole run instead of going dark when the turn that started it ends.
• A workflow is followed as that one task. Plexus reads the workflow's own run record only to count how many of its agents are still going, which is the number the tooltip shows.
• Each running subagent and workflow 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. Teammates, cloud sessions and background shells have no progress Plexus can watch, so they stay until Claude Code stops reporting them, or for at most 6 hours.
• When Claude Code's own record of the session (see The activity dot) says nothing delegated is still running, work that started before that point drops off the ring.
• 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.

The state chip

Next to the session's name, a small chip says where its work stands in words (in the compact density, an icon beside the other indicators): Checks while its pull request's checks run, Review while it waits for one, Ready when it can merge, Merged once it has; and, for a stacked session, Behind, Syncing or Resolving while it catches up with the session under it. A session with nothing to report shows no chip. An amber chip — Needs you: checks failed, Needs you: conflict, … — names the one thing to do, and counts towards N need you like a waiting session does (each session once). The context bar shows the same chip in full words, with a line of detail beside it. Every chip is listed under States.

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 work doesn't change that. While delegated work — background subagents, a workflow, a teammate — 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. A workflow holds the alert back for its whole run, however many phases it has, and you hear about it once when it finishes.

Background shell commands don't hold it back. They don't light the ring either, so a turn that leaves a dev server running alerts you as usual when it ends.

Notices that don't need you don't alert you either: a background agent finishing or a sign-in succeeding doesn't move the dot to waiting, so it doesn't notify you.

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

The dot follows an Esc interrupt and an approved permission prompt on its own now (see The activity dot), so it rarely needs a hand. If it does stick on the wrong state — say, a hook was lost on the way and there was nothing else to correct it from — you can clear it.

Open the session's ⋯ menu and choose to reset its status. The dot flips to idle (gray) immediately, and the background-work ring — which can stick the same way, if a task'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 or workflow 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.

Alongside those four checks, the report shows what Plexus is basing the dot and the ring on right now:

• Claude Code's own status record for the session — whether Plexus found it, what it says the session is doing, and how long ago it was last updated. When there isn't one (older versions of Claude Code don't keep it), Plexus works from the hooks and the conversation record alone.
• What last moved the dot — which signal set its current color, how long ago, and why.
• What's running in the background, by kind — subagents, workflows and how many of their agents are live, teammates, cloud sessions and background shells.

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".