anthropics / anthropics/claude-code
[FEATURE] Group sessions in the agents view by tag (/tag, tag column, collapsible groups)
- Dominant language
- Python
- Stars
- 145k
- Forks
- 23.1k
- PR merge metrics
- PR metrics pending
Description
## Problem Statement
I run many sessions in parallel, and they cluster naturally around a few things: a project or task that spawned several sessions (forks, side discussions, follow-ups), the PR reviews I do for teammates, one-off questions. `claude agents` gives me no way to see those clusters. The list is split only by state (Needs input / Working / Completed), so sessions from one project are scattered across the three sections and mixed with everything else.
The tools that exist do not solve it:
- Pin puts a session at the top, but with several active projects the pinned block is just another mixed list.
- `/rename` with a prefix like `[REVIEW] - ...` and `/color blue` make related sessions look alike, but each has to be done by hand on every session, the prefix eats the name, and the view still does not group or sort by it. It is a visual hint, not grouping.
What I actually need is to look at the screen and see "all sessions for project X" and "all my review sessions" as blocks, and keep track of what is open in each block.
## Proposed Solution
Tags as a first-class field on a session, and grouping in the agents view built on them:
- `/tag ` in a session, `--tag ` on `claude` for headless / background runs. Stored in job metadata next to `name` and `color`. Forked sessions inherit the parent's tags.
- A Tags column in the agents view, in the same style as the existing PR column.
- Group by tag on screen: a collapsible block per tag, with the state indicators kept inside it, so I can collapse `review` and expand `db-migration`.
- Sort by tag as a lighter alternative when grouping is off.
- Optional: a default color per tag, so tagging also colors without a separate `/color`.
## Alternative Solutions
- Prefix + color convention (what I do today). Manual per session, and it does not group.
- A `UserPromptSubmit` hook that writes `name` / `color` into `~/.claude/jobs//state.json`. Fragile, since the daemon owns the file, and still no grouping.
- Related open request: #58243 (sort by most recently updated). Tags would be another sort and group key on the same view.
## Use Case Example
One day: a DB migration project with 5 sessions (planning, two forks trying different approaches, a Slack draft, a status check), 6 PR reviews for teammates, 3 unrelated questions. With tags I run `/tag db-migration` and `/tag review` once per session (forks inherit), then the view shows two blocks I can collapse and expand, plus the untagged rest. Today I rename and color each session by hand and still scan the whole list to find them.
## Additional Context
Claude Code v2.1.274, macOS arm64. Screenshot of the current manual workaround attached.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by tracing the `claude agents` entry point and the existing handling for session name, color, job metadata, and the PR column; the issue identifies `~/.claude/jobs//state.json` as related context. Done should cover `/tag`, `--tag`, persisted tags, a Tags column, and tag-based sorting or grouping, with any default-color behavior explicitly decided.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- cli, developer-experience
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Needs clarification
- Newbie friendliness
- 28/100