Define Custom Subagents on the Fly with --agents

Instead of creating agent definition files, the --agents flag lets you define subagents inline as JSON when launching Claude Code. This is great for quick experiments or CI pipelines where you need specialised agents without committing files to the repo.

claude --agents '{
  "reviewer": {
    "description": "Reviews code for security issues",
    "prompt": "You are a security-focused code reviewer. Flag any potential vulnerabilities, injection risks, or unsafe patterns."
  }
}'

Claude can then spawn the "reviewer" subagent during the session to delegate security review tasks. The JSON structure uses the same fields as subagent frontmatter, so anything you can define in a .md agent file works here too.

You can define multiple agents at once:

claude --agents '{
  "tester": {
    "description": "Writes unit tests",
    "prompt": "Write thorough unit tests with edge cases."
  },
  "documenter": {
    "description": "Writes documentation",
    "prompt": "Write clear, concise documentation for the given code."
  }
}'

This pairs well with --print mode for scripted workflows where you want Claude to orchestrate specialised agents without any interactive setup:

claude -p --agents '{"linter":{"description":"Checks style","prompt":"Check code style"}}' \
  "Review the src/ directory using the linter agent"

Spin up purpose-built agents from the command line, no config files required.

via Claude Code CLI Reference