Skip to content
BENIBIX Learn

--agents Flag

Also known as claude --agents, CLI-defined subagents

It sets up helper agents for one session.

Think of it like

It is like you write a list of helpers for today. It says what each one is good at.

Example

Jack's CI script needs a test-writer helper only in CI. It passes the helper with --agents, so no agent file has to live in the repo.

Why it matters

A script can bring its own helpers, and nothing is left behind after it ends.

Definition

--agents defines subagents for this session in JSON, with no files to save. Each one gets a name, a description of when to use it, a prompt, and if you like its tools and model. With -p, you can pass a path to a JSON file instead. Claude Code checks the JSON at start and stops if it is wrong.

Example code

bash
claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You review code for bugs."}}'
Add a reviewer subagent for this session.
--agents defines the helpers on the right.

Common mistake

Expecting the agents to last. They exist for this session only. Save an agent file to keep one.

Key takeaways

  1. 1
    JSON. Name, description, prompt.
  2. 2
    This session only. No file saved.
  3. 3
    Checked at start. Bad JSON stops it.

Compare

Learn it properly