# --agents Flag

> It sets up helper agents for one session.

**Field:** Artificial Intelligence  
**Category:** Claude Code  
**Also known as:** claude --agents, CLI-defined subagents

## Think of it like

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

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

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.

## Example code

```bash
claude --agents '{"reviewer":{"description":"Reviews code","prompt":"You review code for bugs."}}'
```

Add a reviewer subagent for this session.

## Why it matters

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

## Common mistake

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

## Three principles

- **JSON.** Name, description, prompt.
- **This session only.** No file saved.
- **Checked at start.** Bad JSON stops it.

## Related terms

- [--agent Flag](https://learn.benibix.com/term/ai/agent-flag)
- [Subagent](https://learn.benibix.com/term/ai/subagent)
- [Built-in Subagents](https://learn.benibix.com/term/ai/built-in-subagents)
- [Claude Code Subagent](https://learn.benibix.com/term/ai/claude-code-subagent)

## Told apart from

- [--agent vs --agents](https://learn.benibix.com/compare/agent-flag-vs-agents-flag): 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.

## Taught in

- [System Prompt Flags](https://learn.benibix.com/learn/ai-claude-code-commands/system-prompt-flags): Claude Code Commands, 16/17

![--agent picks who the main session is. --agents defines helpers it can hand work to.](https://learn.benibix.com/diagrams/flag-agent-agents.svg)

---

Source: https://learn.benibix.com/term/ai/agents-flag
Author: Behnia Zarei (a developer in Vienna, Austria, who builds and teaches data, AI and business intelligence at BENIBIX)
Publisher: BENIBIX Learn (https://learn.benibix.com/)
Last updated: 2026-11-17
Licence: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Quote freely with attribution.
