Use --max-turns to Limit How Many Steps Claude Takes Autonomously
When Claude works autonomously — especially in CI or with -p — it decides how many steps to take: reading files, running commands, editing code, running tests. Without a limit, a complex prompt could trigger dozens of tool calls. The --max-turns flag puts a ceiling on that.
# Limit Claude to 5 agentic turns
claude -p --max-turns 5 "fix the failing tests in the auth module"
# Quick lookup — one turn is enough
claude -p --max-turns 1 "what version of Laravel is this project using?"
Each "turn" is one cycle of Claude thinking and taking an action (reading a file, editing code, running a command). A --max-turns 10 means Claude gets up to 10 actions to complete the task. If it hasn't finished by then, it stops and reports what it accomplished so far.
This is especially valuable in CI pipelines where you need predictable execution:
# CI: attempt a fix, but don't let it run forever
claude -p \
--max-turns 15 \
--dangerously-skip-permissions \
"fix the lint errors and run the linter to verify"
Without --max-turns, a vague prompt like "make all the tests pass" could send Claude on a long journey — reading dozens of files, rewriting code, running the suite repeatedly. With a turn limit, you get a bounded operation that either succeeds within budget or stops gracefully.
Some guidelines for choosing limits:
- 1-3 turns — simple lookups, quick questions, reading one file
- 5-10 turns — targeted fixes, small edits with verification
- 10-20 turns — multi-file changes, running tests, iterative fixes
- 20+ — complex refactors, feature implementation, deep debugging
You can combine it with --allowedTools for even tighter control — limit what Claude can do and how many times it can do it.
Set a turn budget before you set Claude loose — predictable automation beats open-ended hope.
via Claude Code
Log in to leave a comment.
When Claude writes error messages, button labels, validation text, or onboarding flows, it defaults to generic developer-speak. Add a "Users" section to your CLAUDE.md describing who your actual users are — their technical level, industry jargon, and what they care about — so Claude writes copy that makes sense to THEM, not to developers.
Use the --agent flag with custom markdown files in .claude/agents/ to launch purpose-built Claude sessions with restricted tools and scoped system prompts.
Every project has traps — the billing module that silently fails if you forget to queue the job, the legacy table with column names that don't match the model, the config value that must be set before tests run. Document these gotchas in your CLAUDE.md so Claude avoids the same mistakes your team spent days debugging.