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