Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix [DOCS] Agent view docs omit `claude agents --json` for scripted session listing [1 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
anthropics/claude-code#60685•Fetched 2026-05-20 03:52:10
View on GitHub
Comments
0
Participants
1
Timeline
4
Reactions
0
Author
coygeekcoygeek
Participants
coygeekcoygeek
Timeline (top)
labeled ×4

Fix Action

Fix / Workaround

| claude agents | Open agent view to monitor and dispatch parallel background sessions. Use --cwd <path> to show only sessions started under that directory. Pass --permission-mode, --model, or --effort to set defaults for dispatched sessions. Accepts --settings, --add-dir, --plugin-dir, and --mcp-config like the top-level claude command. Requires an interactive terminal |

RAW_BUFFERClick to expand / collapse

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/agent-view

Section/Topic

"Manage sessions from the shell" and the claude agents command reference

Current Documentation

The docs currently say:

Every background session has a short ID you can use from the shell. The ID is printed when you start a session with claude --bg, and each session's ID is its directory name under ~/.claude/jobs/. These commands are useful for scripting or when you don't want to open agent view.

| claude agents | Open agent view | | claude agents --cwd <path> | Open agent view scoped to sessions started under <path> |

The CLI reference also currently says:

| claude agents | Open agent view to monitor and dispatch parallel background sessions. Use --cwd <path> to show only sessions started under that directory. Pass --permission-mode, --model, or --effort to set defaults for dispatched sessions. Accepts --settings, --add-dir, --plugin-dir, and --mcp-config like the top-level claude command. Requires an interactive terminal |

What's Wrong or Missing?

The v2.1.145 release notes add claude agents --json to list live Claude sessions as JSON for scripting, but the main docs still describe claude agents only as an interactive agent-view entry point.

That leaves the scripting-oriented session-management docs missing the supported machine-readable command for:

  • session pickers
  • status bars
  • tmux-resurrect or similar restore tooling

The current pages also do not explain whether --cwd can be combined with --json, or position claude agents --json as the supported alternative to inferring session state from local files such as ~/.claude/daemon/roster.json and ~/.claude/jobs/<id>/state.json.

Suggested Improvement

Add claude agents --json to both:

  1. the claude agents row in the CLI reference
  2. the "Manage sessions from the shell" table in agent view

Document at least:

  • that claude agents --json lists live/background sessions as JSON for scripting
  • whether --cwd <path> also works with --json
  • one short example such as claude agents --json for a session picker or status-bar integration

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

PageLine(s)Context
https://code.claude.com/docs/en/agent-view395-400The shell-management section says these commands are useful for scripting, but it lists only claude agents and claude agents --cwd <path>
https://code.claude.com/docs/en/agent-view429-433The same page points readers to local state files such as ~/.claude/daemon/roster.json and ~/.claude/jobs/<id>/state.json, but does not document the new JSON CLI output
https://code.claude.com/docs/en/cli-reference27The claude agents command entry documents interactive usage and --cwd, but not --json

Total scope: 2 pages affected

The missing flag is specifically relevant to the v2.1.145 addition of claude agents --json for scripted session listing.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#API middleware#SSR setup#ISR setup#authentication setup#request error

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

claude-code - 💡(How to fix) Fix [DOCS] Agent view docs omit `claude agents --json` for scripted session listing [1 participants]