Use Multi-Turn Headless Sessions for Complex Automation

Single-turn claude -p is great for one-off tasks. Multi-turn headless sessions let you build complex CI pipelines where each step builds on the previous one’s context.

How It Works

# Start a session and capture the ID
SESSION=$(claude -p "Analyze the code changes in this PR" \
  --output-format json | jq -r '.session_id')

# Continue with context from the first turn
claude -p "Now write tests for the issues you found" \
  --session-id "$SESSION" \
  --output-format json

# Third turn, still has full context
claude -p "Run the tests and fix any failures" \
  --session-id "$SESSION"

Sessions persist server-side for 24 hours.

CI Pipeline Example

# .github/workflows/claude-review.yml
steps:
  - name: Analyze PR
    id: analyze
    run: |
      RESULT=$(claude -p "Review this PR diff for bugs and security issues" \
        --output-format json --allowedTools "Read,Grep,Glob")
      echo "session_id=$(echo $RESULT | jq -r '.session_id')" >> $GITHUB_OUTPUT

  - name: Generate Fix
    if: steps.analyze.outputs.has_issues == 'true'
    run: |
      claude -p "Generate fixes for the issues you found" \
        --session-id ${{ steps.analyze.outputs.session_id }}

Key Flags for CI

• --allowedTools - restrict tool access (security)
• --max-turns - prevent infinite loops
• --output-format json - machine-parseable output

Cost

Average review pipeline: ~8,000 tokens, ~$0.02/run. Multi-turn adds incremental cost per turn but saves tokens vs. re-explaining context.