[FEATURE] CLI flag to list available agents (user-wide and project-scoped)

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

When using Claude Code’s CLI, it can be difficult to keep track of which agents are available, especially as a user works across multiple projects or utilizes user-wide configurations. There is currently no simple command to quickly list all agents accessible to a user or within a project context. This slows down workflows that depend on switching between agents or understanding available automation.

Proposed Solution

Ideally there would be a CLI command or flag such as claude agents --list or claude --list-agents which provides:

• A user-wide listing of all agents currently configured for the account
• A project-scoped listing of agents specific to the active directory/project
• Clear output format, such as tabular or JSON, making it easy to filter and pipe the results

With the command claude agents, we can have subcommands, e.g. running claude agents --list --scope user would show global agents, and claude agents --list --scope project would show only agents relevant to the current project. The feature should respect environment config files and allow filtering or detailed views as needed.

Alternative Solutions

Currently, users must manually check configuration files or documentation, or use trial and error with agent commands. There is no standardized way to get a reliable, up-to-date list of agents. Workarounds include keeping notes outside the tool or scripting custom file searches, but these aren’t user-friendly.

Priority

High - Significant impact on productivity

Feature Category

CLI commands and flags

Use Case Example

Example scenario:

1. As a developer, I need to know which agents I can invoke for code review or test automation in my workspace.
2. After adding a new agent, I want to confirm its availability for my current project context.
3. By using the proposed flag, I quickly see agents available globally and locally, saving time and avoiding confusion about configuration.

Additional Context

• Many CLI tools, such as git (git remote -v) or docker (docker ps), provide commands for listing contextually available resources. This would bring similar clarity to Claude Code.
• Mockup: claude agents --list

User Agents:

• agentA: Code review (Global)
• agentB: Test automation (Global)

Project Agents:

• agentC: Specialized build agent (Project)
• agentD: Custom lint tool (Project)
• Ensures consistency and usability for both frequent and new users.