Feature request: built-in, cross-platform way to list running Claude Code sessions and their state

For context, here's a screenshot of the KDE Plasma widget I built as a workaround (see attached image). It lists each running claude session with a simple traffic-light state:

• 🟢 green — ready, idle, waiting for a new prompt
• 🟠 orange — actively running
• 🔴 red — waiting on me (permission prompt / idle notification)

This is exactly the kind of thing that becomes trivial with a built-in claude sessions list/API, and fragile without one — the hooks + /proc-walking + CPU-heuristic combo described above is the only way I found to get this on Linux, and it doesn't translate to macOS at all. Happy to share the widget's source if useful as a reference for what "good enough" output would look like.

<img width="490" height="511" alt="Image" src="https://github.com/user-attachments/assets/1002a70d-0bc8-4d11-ba5f-d664a7f72b38" />

Related: #88511 requests essentially the same three-state model (running / waiting for input / idle), scoped to the Desktop app's "Recents" list UI rather than an external/CLI interface. Worth noting the reporter there mentions an internal list_sessions API already exposing isRunning — suggesting at least part of this data already exists internally, it's just not exposed to external tools/processes.

Also related, narrower in scope: #90775 (CLI/machine-readable session list, focused on Remote Control reconnection), #76089 and #78595 (same need in the VS Code extension sidebar), #94374 (Desktop: see status of many sessions at once).

One more concrete pain point worth calling out separately: detecting whether a session has an active background task (a Bash tool call started with run_in_background: true) is also not observable externally today, and I tried two different approaches before giving up:

1. Process tree inspection (pstree under the session's claude PID): unreliable in both directions.

• False positive: a persistent MCP server child process is present for the entire life of the session, so "does this PID have child processes" doesn't distinguish idle from busy.
• False negative: a real backgrounded task (sleep 30 &, run_in_background: true) did not show up as a descendant of the claude PID at all while it was running — most likely because of how the sandbox reparents/tracks it.

1. TaskCreated / TaskCompleted hooks: both are present as literal event-name strings in the installed binary (2.1.273), so I wired them up in ~/.claude/settings.json (no matcher) expecting them to fire for background task start/finish. I then ran a real ~6s run_in_background Bash command in a live session — neither hook fired.

So today there is no reliable way, from outside the process, to know "is this session currently running something in the background." If the proposed session-state API/CLI from the issue description above ends up covering this too (e.g. a hasActiveBackgroundTask / backgroundTaskCount field per session), that would fully close this gap as well.

I'm integrating session status into TTYbird on macOS. The useful distinction here is ordinary interactive sessions versus background sessions.

The current agent-view docs already document claude agents --json with status and waitingFor. However, the same page explicitly says interactive sessions open in other terminals do not appear until backgrounded. That leaves a gap for a read-only dashboard that discovers sessions people launched normally, without changing their workflow.

For those sessions, our fallback correlates process identity, open transcript descriptors, and optional hooks. Those are observations at different times, not an authoritative current-state query. We also found and are fixing a stale-hook precedence bug in our collector; that is not evidence of a Claude Code hook defect.

A minimal supported record for all live interactive/background sessions would help:

• stable session ID and session kind;
• PID plus process-start identity, to distinguish restart/PID reuse;
• current busy / waiting / idle state and optional waitingFor;
• observation timestamp or sequence, with explicit unavailable/stale semantics.

No previews, prompts, turns, tool arguments, or credentials are needed. A read-only query should not resume/background a session or subscribe the caller to conversation/approval handling. Extending claude agents --json with an opt-in interactive-session scope would let consumers use one documented interface.

This is based on the current documented scope and integration review (installed CLI 2.1.272), not a claim that I reproduced a new upstream hook failure. Adding these requirements here rather than filing a duplicate.