workflows

>Set Max Turns for Autonomous Mode

autonomousflagsrefactoring
Source:▶How I Start EVERY Claude Code Project|@AI with Avthar

When you're tackling large refactoring tasks or complex code changes, constantly approving each step Claude Code wants to take can slow you down. The --max-turns flag solves this by letting Claude work autonomously for multiple steps, making decisions and applying changes without stopping to ask for approval each time.

This is particularly powerful for systematic changes like updating TypeScript configurations, migrating to new libraries, or refactoring component patterns across your entire codebase. Instead of babysitting each individual file change, you can set boundaries and let Claude work within them.

Understanding How Max Turns Work

The --max-turns flag tells Claude Code how many autonomous decisions it can make before requiring your input. Each "turn" represents one decision point where Claude would normally pause and ask for your approval.

Here's the basic syntax:

claude --max-turns <number> "Your task description"

When you set max turns, Claude will:

  1. Analyze your request and create a plan
  2. Execute the first step
  3. Continue making decisions and applying changes
  4. Stop after the specified number of turns OR when the task is complete
  5. Show you a summary of everything it accomplished

Setting Up Autonomous Refactoring Tasks

Let's look at practical examples of how to use max turns for different types of work.

Large-Scale TypeScript Migrations

When converting a JavaScript project to TypeScript, you'll typically have dozens or hundreds of files that need similar changes:

# Convert all .js files to .ts and add basic type annotations
claude --max-turns 15 "Convert all JavaScript files in src/ to TypeScript, adding basic type annotations and fixing any obvious type errors"

This approach works well because:

  • The changes are systematic and predictable
  • Claude can apply similar patterns across multiple files
  • You trust Claude to make good typing decisions for straightforward cases

Component Library Updates

When updating component patterns across your app, autonomous mode shines:

# Update all React components to use new hook patterns
claude --max-turns 20 "Update all React components to use the new useQuery hook instead of the deprecated fetchData utility, maintaining the same functionality"

Code Style Standardization

For consistency improvements across your codebase:

# Standardize error handling patterns
claude --max-turns 12 "Update all API call error handling to use our new ErrorBoundary pattern instead of try-catch blocks"

Choosing the Right Number of Turns

The key to successful autonomous mode is setting appropriate limits. Too few turns and Claude stops before finishing; too many and you lose control over the process.

Start Conservative for New Projects

When you're first working with a codebase or trying a new type of refactoring:

# Conservative approach for unfamiliar territory
claude --max-turns 5 "Refactor authentication logic to use the new auth service"

Starting with 5-8 turns lets you see how Claude approaches the problem before giving it more autonomy.

Scale Up for Familiar Patterns

Once you're confident in Claude's approach to your codebase:

# More aggressive for well-understood changes
claude --max-turns 25 "Update all database models to include the new audit fields (created_at, updated_at, created_by)"

Consider Task Complexity

Match the turn count to your task's scope:

  • Simple, repetitive changes: 8-15 turns
  • Medium refactoring with some complexity: 15-25 turns
  • Large architectural changes: 25-50 turns (be very careful here)

Monitoring Autonomous Progress

Even in autonomous mode, you should stay engaged with what Claude is doing. Watch for these patterns:

Successful Autonomous Sessions

You'll know things are going well when:

  • Changes follow consistent patterns
  • File modifications make logical sense
  • Claude provides clear commit messages or change summaries
  • No syntax errors or broken imports appear

When to Intervene

Stop and review if you notice:

  • Unexpected file deletions
  • Changes to critical configuration files
  • Modifications that seem to break established patterns
  • Too many failed attempts at the same operation
# If something goes wrong, you can always stop and review
# Claude will show you everything it did so far

Pro Tips for Autonomous Mode

Use Descriptive Task Descriptions

The more specific your request, the better Claude's autonomous decisions:

# Vague - might lead to unexpected changes
claude --max-turns 10 "Clean up the code"

# Specific - Claude knows exactly what to do
claude --max-turns 10 "Remove unused imports and variables, standardize indentation to 2 spaces, and ensure all functions have JSDoc comments"

Set Boundaries in Your Prompt

Include constraints to keep Claude focused:

claude --max-turns 15 "Refactor components to use CSS modules, but don't touch any files in the legacy/ directory and preserve all existing class names for backwards compatibility"

Test in Feature Branches

Always run autonomous refactoring on a separate branch:

# Create a branch first
git checkout -b refactor/typescript-migration

# Then run your autonomous task
claude --max-turns 20 "Convert components to TypeScript strict mode"

This lets you review all changes before merging and easily revert if needed.

Common Pitfalls to Avoid

Don't Set Unlimited Turns

While tempting, avoid extremely high turn counts (50+) unless you're very confident:

# Risky - could make hundreds of changes
claude --max-turns 100 "Modernize the entire codebase"

# Better - break into smaller, focused tasks
claude --max-turns 15 "Update all React class components to functional components with hooks"

Watch for Circular Logic

Sometimes Claude can get stuck in loops, especially with complex dependency issues. If you see the same operations repeated, it's time to intervene.

Don't Skip Testing

After any autonomous session, run your test suite:

# After Claude finishes
npm test
# or
yarn test

Autonomous mode is fast, but it's not infallible.

What's Next

Once you're comfortable with basic autonomous mode, explore combining it with other Claude Code features. You can use --max-turns alongside specific file targeting, custom instructions, or as part of larger workflow automation.

Consider setting up scripts that combine autonomous refactoring with testing and validation steps, creating powerful development workflows that maintain code quality while moving fast.

The key is building trust gradually—start small, observe the patterns, then scale up your autonomous operations as you become more confident in Claude's decision-making for your specific codebase.

←cd ~/tips