{"name":"--agents","slug":"agents","family":"cli","title":"CLI flags","noun":"CLI flag","description":"Define custom subagents dynamically via JSON. Accepts the [fields listed for CLI-defined subagents](\/docs\/en\/sub-agents#choose-the-subagent-scope). 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`](\/docs\/en\/errors#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","description_source":"docs","described_by":{"doc":"claude-code\/cli-reference","title":"CLI reference"},"presence":{"first_seen":"2.1.138","removed_in":null,"in_current_build":true,"newest_mined":"2.1.308","builds":149,"mined_builds":149,"first_cited":{"version":"2.1.193","released_at":"2026-06-25 19:05:08","spans":4}},"aliases":[],"entries":[{"version":"2.1.290","anchor":"spawned-teammates-now-get-proactivity-passed-through","heading":"Teammates now inherit the lead session's proactivity level","line":"Teammates started by a lead session now receive `--proactivity` with the lead's level when one is set","released_at":"2026-10-05 18:12:44","reason":"found in this entry's text"},{"version":"2.1.281","anchor":"agents-can-now-take-a-file-path-instead-of-inline-json-bu","heading":"--agents can now take a file path instead of inline JSON, but only in print mode","line":"--agents now accepts a path to a file of subagent definitions, but only with --print (-p); interactive sessions still need inline JSON","released_at":"2026-09-23 17:01:17","reason":"found in this entry's text, named in this entry"},{"version":"2.1.281","anchor":"self-hosted-runner-server-composed-agent-files-delivered-vi","heading":"Self-hosted runner: server-composed agent files delivered via --agents file; system prompts delivered by file","line":"The self-hosted runner now checks agent_files, passes agents via --agents <file>, and passes system prompts as files","released_at":"2026-09-23 17:01:17","reason":"found in this entry's text, named in this entry"},{"version":"2.1.281","anchor":"tmux-worktree-relaunch-absolutizes-path-arguments","heading":"--tmux worktree relaunch absolutizes path arguments","line":"When --tmux relaunches Claude Code for a worktree, relative file paths in flags are now turned into full paths","released_at":"2026-09-23 17:01:17","reason":"found in this entry's text"},{"version":"2.1.281","anchor":"sandbox-file-paths-supplied-through-the-agents-flag-are-now","heading":"Sandbox: file paths supplied through the agents flag are now write-denied","line":"Inside the sandbox, files you pass through the agents flag can no longer be written to","released_at":"2026-09-23 17:01:17","reason":"named in this entry"},{"version":"2.1.281","anchor":"bg-rejects-agents-given-as-a-file","heading":"--bg rejects --agents given as a file","line":"Using --bg with --agents pointing at a file now fails; pass the agents as inline JSON instead","released_at":"2026-09-23 17:01:17","reason":"found in this entry's text, named in this entry"},{"version":"2.1.281","anchor":"a-json-file-passed-to-agents-is-now-protected-like-a-setti","heading":"A JSON file passed to --agents is now protected like a settings file","line":"A JSON file passed to --agents is now protected from edits the same way Claude Code's settings files are","released_at":"2026-09-23 17:01:17","reason":"found in this entry's text, named in this entry"},{"version":"2.1.234","anchor":"early-flag-scan-no-longer-mistakes-tool-lists-and-directorie","heading":"Early flag scan no longer mistakes tool lists and directories for flags","line":"Tool lists and directories passed to flags are no longer misread as flags themselves at startup.","released_at":"2026-08-17 18:19:13","reason":"named in this entry, found in this entry's text"},{"version":"2.1.234","anchor":"spawned-processes-get-flag-value-when-the-value-looks-like-a","heading":"Spawned processes get --flag=value when the value looks like a flag","line":"Prompts and model names starting with a dash are no longer swallowed as options by subagents and background tasks.","released_at":"2026-08-17 18:19:13","reason":"found in this entry's text"},{"version":"2.1.232","anchor":"cloud-gateway-sign-in-explains-its-restart-and-refuses-when-","heading":"Cloud gateway sign-in explains its restart, and refuses when it cannot","line":"Cloud gateway sign-in explains its restart, and ends the session when a restart can't carry state.","released_at":"2026-08-13 21:30:53","reason":"found in this entry's text"}],"entries_total":12,"docs":[{"source":"claude-code","path":"cli-reference","title":"CLI reference","documented":true},{"source":"claude-code","path":"changelog","title":"Claude Code changelog","documented":false},{"source":"claude-code","path":"errors","title":"Error reference","documented":false},{"source":"claude-code","path":"fullscreen","title":"Fullscreen rendering","documented":false},{"source":"claude-code","path":"headless","title":"Run Claude Code programmatically","documented":false},{"source":"claude-code","path":"managed-settings","title":"Deploy managed settings","documented":false},{"source":"claude-code","path":"mcp","title":"Connect Claude Code to tools via MCP","documented":false},{"source":"claude-code","path":"plugins\/mods\/admin","title":"Manage mods for your organization","documented":false},{"source":"claude-code","path":"plugins\/org","title":"Manage Claude Code plugins for your organization","documented":false},{"source":"claude-code","path":"plugins\/troubleshooting","title":"Troubleshoot plugins","documented":false}],"docs_total":12,"gates":[],"related":[],"url":"https:\/\/changelogs.core-directive.com\/reference\/cli\/agents","family_url":"https:\/\/changelogs.core-directive.com\/reference\/cli.json"}