claude-code - 💡(How to fix) Fix [FEATURE] User-defined groups for background/polling agents in agents UI

Problem Statement

I run a handful of long-lived background agents that poll on a schedule (CI watchers, inbox sweeps, status loops) alongside normal one-shot agents. In the current claude agents UI they all sit in one flat list sorted by recency and status. Grouping is implicit (project cwd, running vs idle) and not something I can override.

Polling agents work differently than interactive ones. I don't context-switch into them, I just want to glance and see they're healthy. Today they clutter the list of sessions I'm actually working in, and filtering by status doesn't help. A polling agent mid-tick looks identical to an interactive one I'm waiting on.

Proposed Solution

A way to mark a session as part of a named group, with the agents UI rendering each group as its own collapsible section.

Three shapes that would work, in order of preference:

1. Tags or labels on a session. claude agents tag <id> polling, with the UI grouping by tag. Lightest touch, no schema change beyond a tag list.
2. A group: field in per-project .claude/settings.json or an env var read at session start. Good if you want grouping to follow the launch context rather than be applied after the fact.
3. A reserved background role distinct from running and idle. The UI sections on role, and a session opts in via flag (claude --background) or settings.

Tags feel lightest. Settings field plus CLI flag also fine.

Alternative Solutions

Two workarounds I use today, both partial:

• Distinct cwd per polling agent so they sort together by project. Works, but couples grouping to filesystem layout and pollutes per-project session lists with non-project agents.
• Distinct tmux session names. Only helps inside tmux, and doesn't reach the desktop app or web agents view at all.

Neither survives crossing surfaces (CLI vs desktop vs web).

Priority

Medium - Would be very helpful

Feature Category

Interactive mode (TUI)

Use Case Example

1. I have ~6 polling agents running across two machines: a CI status watcher, two inbox sweepers (GitHub, Linear), a Sentry triage loop, a deploy-status loop, and a daily-recap aggregator.
2. I also have 3-5 interactive sessions open at any time for actual feature work.
3. When I open the agents view I want the polling fleet collapsed into one section labeled "polling" so I can scan health at a glance, and the interactive sessions surfaced separately.
4. Today I scan the whole list and mentally re-classify each row every time, which scales badly as the polling fleet grows.

Additional Context

The grouping needs to work across the CLI agents picker, the desktop app's session list, and the web agents view. A grouping mechanism that only works in one surface would still leave the others noisy.

Related upstream: this is adjacent to but distinct from the existing background-task issues (#55893, #51673, #56930), which are about agent lifecycle and message delivery rather than UI organization.