Skip to content
BENIBIX Learn

--agent vs --agents

People think --agent and --agents are the singular and plural of one flag. They do different jobs. --agent picks a custom agent and runs the main session as it, with that agent's prompt, tools and model. --agents defines new subagents in JSON for this session, helpers the main session can hand work to. You can use both: --agent sets who is in charge, and --agents adds the team.

AI⌨️ Claude Code

--agent Flag

It runs the main session as one of your custom agents.

--agent runs the main session as one of your custom agents. The session takes that agent's prompt, its tools and its model. Give it the agent's name. It wins over the agent setting, for this session only.

Example
Lucy has a reviewer agent with its own rules and only read tools. She starts claude --agent with its name. The whole chat then runs as that agent.
Why it matters
A role you set up once can be the whole session, not just a helper Claude calls.
Full entry
AI⌨️ Claude Code

--agents Flag

It sets up helper agents for one session.

--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
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.
Full entry

In one line

--agent Flag
It runs the main session as one of your custom agents.
--agents Flag
It sets up helper agents for one session.