--agents
A Claude Code CLI flag, read out of the shipped bundle. It has been in the build since v2.1.138, including the newest one read.
Define custom subagents dynamically via JSON. Accepts the fields listed for CLI-defined subagents. With --print, the value can instead be the path to a JSON file holding the object; the file form requires Claude Code v2.1.281 or later. Claude Code validates the value at startup and exits on an invalid one; see Invalid --agents configuration for the message and for the flags and environment variable that skip the validation. Validation requires Claude Code v2.1.242 or later
Anthropic's own wording. Read off CLI reference, captured 2026-09-26.
In the changelogs
12Releases whose published page names --agents.
-
v2.1.290
Teammates now inherit the lead session's proactivity level
Teammates started by a lead session now receive
--proactivitywith the lead's level when one is setfound in this entry's text
-
v2.1.281
--agents can now take a file path instead of inline JSON, but only in print mode
--agents now accepts a path to a file of subagent definitions, but only with --print (-p); interactive sessions still need inline JSON
found in this entry's text, named in this entry
-
v2.1.281
Self-hosted runner: server-composed agent files delivered via --agents file; system prompts delivered by file
The self-hosted runner now checks agent_files, passes agents via --agents <file>, and passes system prompts as files
found in this entry's text, named in this entry
-
v2.1.281
--tmux worktree relaunch absolutizes path arguments
When --tmux relaunches Claude Code for a worktree, relative file paths in flags are now turned into full paths
found in this entry's text
-
v2.1.281
Sandbox: file paths supplied through the agents flag are now write-denied
Inside the sandbox, files you pass through the agents flag can no longer be written to
named in this entry
-
v2.1.281
--bg rejects --agents given as a file
Using --bg with --agents pointing at a file now fails; pass the agents as inline JSON instead
found in this entry's text, named in this entry
-
v2.1.281
A JSON file passed to --agents is now protected like a settings file
A JSON file passed to --agents is now protected from edits the same way Claude Code's settings files are
found in this entry's text, named in this entry
-
v2.1.234
Early flag scan no longer mistakes tool lists and directories for flags
Tool lists and directories passed to flags are no longer misread as flags themselves at startup.
named in this entry, found in this entry's text
-
v2.1.234
Spawned processes get
--flag=valuewhen the value looks like a flagPrompts and model names starting with a dash are no longer swallowed as options by subagents and background tasks.
found in this entry's text
-
v2.1.232
Cloud gateway sign-in explains its restart, and refuses when it cannot
Cloud gateway sign-in explains its restart, and ends the session when a restart can't carry state.
found in this entry's text
-
v2.1.193
disableSideloadFlagsEnterprise Settingfound in this entry's text
-
v2.1.169
Safe Mode (
--safe-mode/CLAUDE_CODE_SAFE_MODE)found in this entry's text
First cited
4The earliest release whose published evidence quoted --agents was v2.1.193, 25 Jun 2026. That is the oldest release this project wrote about it, so it is a floor on the name's age and not the release that introduced it. It is not a presence reading: which builds carried the name is the table below.
Presence across releases
1Build by build
149One row per release since the first build this name was read out of. Absent means the build was read and the name was not in it, never mined means no bundle for that release was ever archived, and a declared type or a default is only ever what that release's own bundle stated.
Read out of the published npm bundle release by release, and out of Anthropic's own documentation as this site captured it. Nothing on this page is a description anybody here wrote about what the CLI flag does. All CLI flags.