# --max-turns Flag

> It caps how many turns claude -p may take.

**Field:** Artificial Intelligence  
**Category:** Claude Code  
**Also known as:** claude --max-turns, Turn limit, CLAUDE_CODE_MAX_TURNS

## Think of it like

It is like a game where you get three tries, then you have to stop.

## Definition

--max-turns sets how many turns claude -p may take before it stops. A turn is one round where Claude acts, such as running a tool, then reads what came back. There is no limit unless you set one. It keeps a run that is stuck from going round and round.

## Example

Lucy's CI job asks Claude to fix lint errors. She sets --max-turns 10, so a run that cannot find a fix stops instead of using up the job's time.

## Example code

```bash
claude -p --max-turns 3 "Fix the typo in README.md"
```

Stop after three turns at most.

## Why it matters

A run with no end costs time and money. A cap puts a ceiling on both.

## Common mistake

Setting it too low for a real task. A fix that needs ten steps stops at three, half done.

## Three principles

- **Print mode only.** With -p.
- **No limit.** Unless you set one.
- **Too low.** Stops work half done.

## Related terms

- [Non-Interactive Mode](https://learn.benibix.com/term/ai/non-interactive-mode)
- [--max-budget-usd Flag](https://learn.benibix.com/term/ai/max-budget-usd-flag)
- [Agent Loop](https://learn.benibix.com/term/ai/agent-loop)

## Told apart from

- [--max-turns vs --max-budget-usd](https://learn.benibix.com/compare/max-turns-flag-vs-max-budget-usd-flag): People think --max-turns and --max-budget-usd are two ways to set the same limit. They count different things. --max-turns counts rounds: each time Claude acts and reads the result is one turn. --max-budget-usd counts dollars, using Claude Code's own estimate. A run with few turns can still cost a lot if each turn reads big files. A cheap run can still take many turns. Set both on unattended runs.

## Taught in

- [Print Mode Output Flags](https://learn.benibix.com/learn/ai-claude-code-commands/print-mode-output-flags): Claude Code Commands, 14/17

![Three limits on a print mode run: turns, dollars, and permission prompts nobody can answer.](https://learn.benibix.com/diagrams/flag-limits.svg)

---

Source: https://learn.benibix.com/term/ai/max-turns-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-16
Licence: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Quote freely with attribution.
