# --agent Flag

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

**Field:** Artificial Intelligence  
**Category:** Claude Code  
**Also known as:** claude --agent, agent setting

## Think of it like

It is like a friend plays the coach. They play that part the whole game.

## Definition

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

## Example code

```bash
claude --agent code-reviewer
```

Start a session as the code-reviewer agent.

## Why it matters

A role you set up once can be the whole session, not just a helper Claude calls.

## Common mistake

Mixing it up with --agents. --agent picks who the main session is. --agents defines helpers.

## Three principles

- **Main session.** As that agent.
- **Its prompt, tools, model.** All of them.
- **Beats the setting.** This session.

## Related terms

- [--agents Flag](https://learn.benibix.com/term/ai/agents-flag)
- [Subagent](https://learn.benibix.com/term/ai/subagent)
- [Built-in Subagents](https://learn.benibix.com/term/ai/built-in-subagents)

## 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/agent-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.
