Feature request: scope `claude agents` view to current project / CWD

[zentrolink-ivanzhukov]

Problem

When running claude agents from inside a project directory, the agent session list currently shows all agentic sessions across all projects on the machine. There is no way to filter the list to the project I'm currently in.

For users who run Claude across many unrelated projects (different repos, different working directories), this makes the list unusable as a per-project task tracker. The view conflates contexts that should be kept separate.

Current behavior

cd ~/projects/foo
claude agents
# → shows sessions from ~/projects/foo, ~/projects/bar, ~/work/baz, etc., all mixed together

Desired behavior

By default, claude agents invoked from a directory shows only sessions whose original CWD matches the current project root (or current working directory).

Optional flags to broaden the view explicitly:

• claude agents --all — current behavior (every session, every project)
• claude agents --scope=cwd — only sessions started in the exact current directory
• claude agents --scope=project (default) — sessions whose CWD is under the current project root, detected via nearest .git parent or similar
• claude agents --scope=global — same as --all

A config key in ~/.claude/settings.json could set the default scope (agents.defaultScope: "project" | "cwd" | "global").

Why

• Each project has its own conversational context, its own goals, its own tasks. Mixing them obscures rather than informs.
• It's the natural mental model — every other dev tool that lists "open work" (VS Code recent, JetBrains projects, git status, tmux sessions) operates within a project scope by default.
• For users running 10–30 projects with concurrent Claude sessions, the global list rapidly becomes unreadable.

Related

• claude --bg and the background service introduced in 2.1.139 make multi-project agent work much more practical. Per-project scoping in the agents view is the natural completion of that workflow.

Thanks for considering!

[zentrolink-ivanzhukov]

Update — found a partial workaround: pressing Ctrl+S in claude agents toggles sorting/grouping by directory, which brings same-folder sessions together. Useful, but the underlying need is broader UX, not just sorting.

What I'd like to see in the agents view when running many parallel sessions:

• Per-folder visibility toggles — collapse/hide entire project groups so I can focus on one or two without losing the others.
• Solo / focus mode — single keystroke that hides every group except the one under the cursor (and a way to bring others back).
• Color coding per project — distinct accent color per directory, persisted, so the eye can parse the list at a glance.
• Optional default filter in ~/.claude/settings.json — e.g. agents.defaultScope: "project" to start the view scoped to the current repo, expand with a keystroke.
• Visual separators between groups beyond the current dim header — empty line / divider / fold indicator.

The pain isn't strictly "filter to current project" — it's that the view becomes a wall of text as soon as you run more than ~10 concurrent sessions across a few projects. Sorting alone (Ctrl+S) helps but doesn't scale; the view needs affordances to mute / focus / visually separate.

Keeping the issue open as a UX-improvement request rather than a strict scope filter.

[bogini]

This shipped in v2.1.141 — claude agents --cwd <path> scopes the view to sessions whose dispatch origin is <path> or a subdirectory. Worktree-dispatched jobs are matched against their parent project (so a job running in ~/projects/my-app/.claude/worktrees/foo still shows under --cwd ~/projects/my-app).

claude agents --cwd .                    # sessions from current directory
claude agents --cwd ~/projects/my-app    # sessions from a specific project

Thanks for the request!

[zentrolink-ivanzhukov]

Heads-up for anyone following: v2.1.141 isn't on the public update channel yet.

Verified today:

$ claude --version
2.1.140 (Claude Code)

$ claude update
Current version: 2.1.140
Checking for updates to latest version...
Claude Code is up to date (2.1.140)

$ claude install latest
✔ Claude Code successfully installed!
  Version: 2.1.140

$ claude install 2.1.141
✘ Installation failed
Request failed with status code 404

So the --cwd flag mentioned above can't be exercised by end users yet — both latest and an explicit claude install 2.1.141 fail to retrieve it. Looks like a staged rollout or the release just hasn't reached the public download server. Will retry over the next few days.

Not a blocker for closing the issue — just flagging in case anyone else tries the flag right now and gets error: unknown option '--cwd'.

[zentrolink-ivanzhukov]

Update — fixed. v2.1.142 is now on the public update channel and includes --cwd. Verified:

$ claude --version
2.1.142 (Claude Code)

$ claude agents --help | grep -A1 cwd
  --cwd <path>                    Show only background sessions started under
                                  <path>

So the rollout caught up, and the alias works as advertised. Closing the loop on my previous comment — nothing more needed here, this can stay closed.

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.