Use --max-turns to Limit How Far Claude Goes Before Checking In
Claude Code can chain dozens of tool calls autonomously — reading files, running tests, editing code, running tests again. That's powerful, but sometimes you want a shorter leash.
claude --max-turns 5 -p "refactor the auth middleware"
Claude will work through up to 5 tool-use turns, then stop and return what it has — even if the task isn't finished. You can review the progress and decide whether to continue.
This is especially useful in a few scenarios:
# Quick analysis — read a few files and report, don't start changing things
claude --max-turns 3 -p "what's the architecture of this project?"
# Controlled refactoring — make some changes then pause for review
claude --max-turns 10 -p "update all API endpoints to use the new auth middleware"
# CI pipeline — don't let Claude run forever
claude --max-turns 20 -p "review this PR for issues" --output-format json
Without --max-turns, Claude keeps going until the task feels complete or it runs out of context. With it, you get a checkpoint.
In non-interactive mode (-p), this is essential. Without a human in the loop to press Escape, --max-turns is your safety valve against runaway execution. Claude still does its best work within the limit — it prioritizes the most impactful steps first.
For interactive sessions, you don't usually need this since you're reviewing each response. But for scripts, cron jobs, and CI, --max-turns is the difference between a helpful assistant and an unsupervised agent.
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.