Claude Code --bare Flag: Headless Automation and Scripted Execution

What Is the Claude Code --bare Flag?

On March 20, 2026, Anthropic added the --bare flag to Claude Code — a new option designed for scripted, non-interactive execution. When combined with the -p (prompt) flag, --bare skips all unnecessary initialization overhead, giving you the fastest possible startup time for automated workflows.

If you're running Claude Code inside CI/CD pipelines, batch scripts, or cron jobs, --bare is exactly what you've been waiting for. It strips away hooks, LSP connections, plugin syncing, and skill directory scanning — leaving you with a lean, predictable execution environment.

Before --bare, running Claude Code with -p still triggered all of these background processes. For a single invocation that didn't matter much, but in batch scenarios where you might run Claude dozens of times in succession, the cumulative startup overhead added up. The --bare flag solves this problem cleanly.

Getting Started with --bare

Basic Syntax

The --bare flag must always be paired with -p (prompt mode):

# Basic usage
claude -p "Find bugs in this code" --bare
 
# Explicitly specifying your API key
ANTHROPIC_API_KEY=sk-ant-xxx claude -p "Generate unit tests for src/utils.ts" --bare
 
# Get structured JSON output
claude -p "Analyze the dependencies in package.json" --bare --output-format json

What --bare Skips

When you pass --bare, the following initialization steps are completely bypassed:

✗ Hooks (pre-tool-use / post-tool-use hooks)
✗ LSP (Language Server Protocol) connections
✗ Plugin synchronization
✗ Skill directory scanning
✗ OAuth / keychain authentication
✗ Auto-memory features

This results in significantly faster startup and a clean execution environment with no external dependencies.

Authentication Constraints

Since --bare disables OAuth and keychain auth, you're limited to two authentication methods:

# Option 1: Environment variable (recommended)
export ANTHROPIC_API_KEY="sk-ant-your-key-here"
claude -p "Analyze this code" --bare
 
# Option 2: API key helper via --settings
claude -p "Analyze this code" --bare \
  --settings '{"apiKeyHelper": "op read op://vault/anthropic/api-key"}'

Practical Example: Automated Code Review in GitHub Actions

One of the most compelling use cases for --bare is automated code review in CI/CD pipelines:

# .github/workflows/claude-review.yml
name: Claude Code Review
on:
  pull_request:
    types: [opened, synchronize]
 
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
 
      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code
 
      - name: Run Claude Review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          # Get the diff against the base branch
          DIFF=$(git diff origin/main...HEAD)
 
          # Fast review with --bare
          claude -p "Review the following code diff.
          Flag any bugs, security issues, or performance concerns.
 
          $DIFF" \
            --bare \
            --output-format json \
            --max-turns 3 \
            --max-budget-usd 0.50

Here's why this configuration works well:

--bare eliminates startup overhead in the ephemeral CI environment
--max-turns 3 caps reasoning loops to prevent runaway execution
--max-budget-usd 0.50 sets a hard cost ceiling per review
--output-format json makes the output easy to parse for downstream steps

Practical Example: Batch Test Generation

Here's a script that generates unit tests for any source file that doesn't already have them:

#!/bin/bash
# generate-tests.sh — Batch generate tests for uncovered files
 
set -euo pipefail
 
find src/ -name "*.ts" -not -name "*.test.ts" -not -name "*.d.ts" | while read -r file; do
  test_file="${file%.ts}.test.ts"
 
  if [ ! -f "$test_file" ]; then
    echo "📝 Generating test: $file"
 
    claude -p "Generate unit tests for the following file.
    Use Jest and cover all major functions.
    Output only the test file contents.
 
    File: $file
    $(cat "$file")" \
      --bare \
      --max-turns 5 \
      --output-format text > "$test_file"
 
    echo "✅ Done: $test_file"
  fi
done
 
echo "🎉 Batch test generation complete"

The key advantage here is speed — without --bare, each iteration would spend time initializing hooks and scanning for plugins. Over dozens of files, the savings are significant.

Combining --bare with the --channels Permission Relay

Another feature that shipped on the same day (March 20) is the --channels permission relay, which forwards tool approval prompts to your phone via Telegram or Discord. When combined with --bare, you get a powerful pattern: automated execution with human oversight for critical operations.

# Forward approval prompts to your phone
claude -p "Run the production database migration" \
  --bare \
  --channels permission-relay \
  --max-turns 10
 
# What happens:
# 1. --bare ensures fast startup
# 2. When Claude attempts file changes or command execution,
#    an approval request is sent to Telegram/Discord
# 3. You approve or deny from your phone
# 4. Execution continues after approval

This strikes the right balance between automation efficiency and human-in-the-loop safety — especially for high-stakes operations.

Safety Best Practices for --bare Automation

When running Claude Code in automated workflows, safety guardrails are essential:

# Recommended: Always set these three safety flags together
claude -p "$PROMPT" \
  --bare \
  --max-turns 5 \        # Cap reasoning loops
  --max-budget-usd 1.00  # Set cost ceiling (USD)
 
# For stricter control
claude -p "$PROMPT" \
  --bare \
  --max-turns 3 \
  --max-budget-usd 0.50 \
  --output-format json \
  --allowedTools "Read,Grep,Glob"  # Restrict available tools

Safety Checklist for Production

Before deploying --bare in production, make sure you've addressed these items:

Always set --max-turns — prevents infinite reasoning loops
Always set --max-budget-usd — prevents unexpected cost spikes
Use least-privilege API keys — create a dedicated key with minimal permissions
Validate outputs — never execute Claude's output directly without validation
Use branch protection — route all changes through pull requests

When to Use --bare vs. Standard -p Mode

The --bare flag is powerful, but it's not always the right choice:

| Scenario | Recommended Mode | Why | |---|---|---| | CI/CD pipelines | -p --bare | Fast startup, no external dependencies | | Batch scripts | -p --bare | Cumulative time savings over many runs | | Cron jobs | -p --bare | Minimal environment, stable execution | | Local development | -p (without bare) | Hooks and plugins add real value | | MCP server workflows | -p (without bare) | LSP and plugins are needed | | Interactive coding | Normal mode | Full UI is required |

Wrapping Up

The --bare flag is a significant quality-of-life improvement for anyone running Claude Code in automated workflows. By stripping away unnecessary initialization, it delivers faster startup times and a more predictable execution environment — exactly what you need in CI/CD pipelines and batch scripts.

Start small: try adding --bare to a simple automation script, then gradually incorporate it into your GitHub Actions workflows and scheduled jobs. Combined with --max-turns, --max-budget-usd, and the new --channels permission relay, you have a robust toolkit for safe, efficient headless automation.

For more on Claude Code automation, check out the [Batch Command Guide]((/articles/claude-code/claude-code-batch-command-guide) and the [CI/CD Integration Guide]((/articles/claude-code/ci-cd-integration).