Skip to content

Claude Code Complete Guide

Claude Code /batch vs claude -p: Parallel Changes or CI Automation

Claude Code has two different ways to run work at scale. Use /batch to split one repository-wide change across independent worktrees and pull requests. Use claude -p when a script or CI job needs one non-interactive result.

Key Points

Key Points

  • /batch is a bundled skill that plans 5–30 independent units and runs each in an isolated Git worktree
  • Headless mode (claude -p) provides non-interactive integration for CI/CD pipelines and shell scripts
  • The two serve distinctly different use cases and can be combined to automate the entire development workflow

Audience:

Intermediate to advanced Claude Code users looking to scale up with large-scale changes and CI/CD integration

/batch Command vs. Headless Mode

/batch and claude -p are often confused, but they serve entirely different purposes. The former automates codebase-wide migrations with parallel agents. The latter is a non-interactive execution mode for embedding AI processing into CI/CD pipelines.

Aspect/batch CommandHeadless Mode (claude -p)
ExecutionSlash command within an interactive sessionOne-shot execution from terminal
Primary UseCodebase-wide migration and refactoringCI/CD integration, script automation, pipe processing
ParallelismAutomatically spawns multiple agents in parallelParallel control via shell scripts
Git IntegrationGit Worktree isolation per agent, automatic PR creationStandard Git operations (script-dependent)
Output boundaryOne pull request per independent unitStandard output or structured JSON

Choose /batch when applying bulk changes across an entire project. Choose headless mode when embedding AI processing into existing CI/CD pipelines.

/batch Command: Parallel Execution of Large-Scale Code Changes

Basic Usage

/batch is a bundled skill invoked with slash-command syntax inside an interactive Claude Code session.1 It researches the repository, proposes 5–30 independent units, waits for plan approval, and then creates one worktree-isolated background agent per unit.2

/batch migrate from React to Vue
/batch replace all uses of lodash with native equivalents
/batch add type annotations to all untyped function parameters
/batch rename all database columns from camelCase to snake_case

When executed, an internal orchestrator agent launches and processes the work in three phases.

The Three Internal Phases

Phase 1: Research and Plan

The orchestrator enters plan mode and launches an Explore agent to investigate the codebase. It identifies target files, patterns, and call sites, then decomposes the work into 5 to 30 independent units. Each unit must be independently mergeable with no dependencies on other units.

Verification methods (CLI tests, existing test suites, etc.) are also determined during planning. If no verification path can be identified, the user is prompted before execution proceeds.

Phase 2: Spawn Workers

After plan approval, one background agent is spawned per unit. All agents run simultaneously in true parallel. Each agent is configured with:

  • isolation: "worktree" for Git Worktree isolation
  • A self-contained prompt including overall goals and individual tasks
  • Codebase conventions discovered during the research phase
  • Test execution instructions

Each worker implements its unit, runs relevant tests, and opens a pull request. Review the proposed decomposition before approval: work that depends on another unit's unfinished code is a poor fit for /batch.

Phase 3: Track Progress

The orchestrator displays a status table that updates as agents complete. The final output is a summary like "22/24 units landed as PRs."

Git Worktree Isolation

The reliability of /batch rests on Git Worktree isolation. Each agent has its own branch and working copy, preventing interference with other agents' changes.

Approved plan
├── Unit 1 → isolated worktree → pull request
├── Unit 2 → isolated worktree → pull request
└── Unit 3 → isolated worktree → pull request

True parallel execution is achieved without merge conflict risk. Since each unit's output is an independent PR, failure in one unit does not affect others.

When to Use /batch

Well-suited tasks:

  • Framework migrations (React to Vue, Jest to Vitest, etc.)
  • Updating all call sites after an API contract change
  • Naming convention unification (camelCase to snake_case, etc.)
  • Library replacement (axios to fetch wrapper, etc.)

Unsuitable tasks:

  • Changes with strong inter-file dependencies (Agent A creates a utility that Agent B imports)
  • Exploratory refactoring with unclear goals
  • Single-file changes

For work requiring cross-unit coordination, Agent Teams or standard Claude Code sessions are more appropriate.

Review the Result with /simplify

/simplify is another bundled skill. Run it when you want Claude to review recent changes for reuse, quality, and efficiency before you merge a result.1

# /simplify can also be used standalone
/simplify
/simplify focus on error handling

Do not assume that a pull request is correct merely because /batch created it. Keep repository CI and human review as the merge gate.

Headless Mode (claude -p): CI/CD and Script Integration

Basic Syntax

Adding the -p (--print) flag runs Claude Code in non-interactive mode3. It processes the prompt, outputs the result to stdout, and exits.

# Basic execution
claude -p "Explain the project architecture"

# Data processing via pipe
cat error.log | claude -p "Summarize the key errors in this log"

# File input and output redirection
claude -p "Review for security vulnerabilities" < app.py > security_report.txt

Output Formats

Three output formats are available, each suited to different use cases.

# Text format (default) — for human consumption
claude -p "Summarize this file" --output-format text

# JSON format — recommended for automated processing and CI/CD
claude -p "List all TODO comments" --output-format json

# Streaming JSON format — for real-time processing
claude -p "Process this large dataset" --output-format stream-json

JSON output can be processed with jq for extracting response text or checking token usage.

# Extract response text only
claude -p "Analyze this code" --output-format json | jq -r '.result'

# Check token usage
claude -p "Summarize this file" --output-format json | jq '.usage'

Tool Permission Control

Headless mode cannot prompt for interactive permission confirmation. Use the --allowedTools flag to explicitly specify permitted tools.

# Read-only (safe)
claude -p "Analyze the code" --allowedTools "Read,Grep,Glob"

# Limited write permissions
claude -p "Fix the bug" --allowedTools "Read,Write,Edit"

# Git operation permissions (prefix matching)
claude -p "Create a commit from staged changes" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git commit *)"

--allowedTools supports prefix matching. Bash(git diff *) permits all commands starting with git diff. Note that spacing matters: Bash(git diff*) would also match git diff-index and similar commands.

Permission Setting Caution

The --dangerously-skip-permissions flag bypasses all permission checks unconditionally. Use only in fully isolated environments such as CI/CD containers. Not recommended for production or local development environments.

Multi-Turn Sessions

Session IDs allow context to persist across multiple claude -p invocations.

# First invocation
claude -p "Review performance issues"

# Continue the most recent session
claude -p "Focus on database queries" --continue

# Continue a specific session by ID
session_id=$(claude -p "Start review" --output-format json \
  | jq -r '.session_id')
claude -p "Continue the review" --resume "$session_id"

Sessions retain approximately 200,000 tokens of context. However, token consumption increases with each turn. Use --max-turns to limit execution turns for cost management.

System Prompt Customization

Four flags control the runtime prompt.

# Add instructions while keeping defaults (recommended)
gh pr diff "$1" | claude -p \
  --append-system-prompt "Review as a security engineer for vulnerabilities" \
  --output-format json

# Add instructions from file (for team sharing)
claude -p "Review the code" \
  --append-system-prompt-file ./review-rules.md

# Complete prompt replacement (advanced use)
claude -p "Analyze" --system-prompt "You are a senior architect."

--append-system-prompt adds instructions while preserving Claude Code's default capabilities. This is appropriate for most use cases. --system-prompt completely replaces the default instructions and should only be used when built-in features are not needed.

CI/CD Pipeline Integration

Since /batch is a session-internal command, it cannot be embedded in CI/CD. Headless mode (claude -p) is the tool for pipeline integration.

GitHub Actions

name: AI Code Review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  claude-review:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Install Claude Code
        run: |
          curl -sSL https://claude.ai/install.sh | sh
          echo "$HOME/.claude/bin" >> $GITHUB_PATH

      - name: Security Analysis
        run: |
          git diff origin/main...HEAD | claude -p \
            --append-system-prompt "Analyze vulnerabilities as a security engineer" \
            --output-format json > security-report.json

      - name: Post Review Comment
        uses: actions/github-script@v6
        with:
          script: |
            const report = require('./security-report.json');
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: report.result
            });

GitLab CI

stages:
  - analysis
  - report

code_analysis:
  stage: analysis
  image: ubuntu:latest
  before_script:
    - apt-get update && apt-get install -y curl jq
    - curl -sSL https://claude.ai/install.sh | sh
    - export PATH="$HOME/.claude/bin:$PATH"
  script:
    - claude -p "Analyze maintainability issues" --output-format json
        > maintainability.json
    - claude -p "Check for performance bottlenecks" --output-format json
        > performance.json
  artifacts:
    paths:
      - "*.json"
    expire_in: 1 week

Shell Script Batch Processing

#!/bin/bash
set -euo pipefail

# Batch review of multiple files
review_code() {
  local file="$1"
  claude -p "Review for quality and security concerns" \
    --allowedTools "Read,Grep,Glob" \
    --output-format json < "$file" \
    | jq -r '.result'
}

echo "# Code Review Report" > review_report.md
echo "Generated: $(date)" >> review_report.md

for file in src/*.py; do
  echo "Reviewing: $file"
  echo -e "\n## $file\n" >> review_report.md
  review_code "$file" >> review_report.md
done

echo "Review complete: review_report.md"

For parallel execution, combine with GNU parallel.

# Process files with 4 parallel workers
find src -name "*.py" | parallel -j 4 \
  claude -p "Optimize this code" \
    --allowedTools "Read" < {} "> optimized/{/}"

Practical Best Practices

When Using /batch

  • Review the planning phase carefully. Verify that the proposed file decomposition is appropriate before approving execution
  • Confirm independence. If shared utilities need to be created first, do so in a regular session before running /batch

When Using Headless Mode

  • Minimize permissions. For read-only analysis tasks, --allowedTools "Read,Grep,Glob" is sufficient
  • Limit turns. --max-turns 1 to 3 is enough for most simple tasks
  • Use JSON output. For automated processing, use --output-format json and parse with jq

Cost Optimization

Repeated multi-turn calls retain more context than a tightly scoped one-shot task. For independent file checks, short claude -p calls are easier to budget. For architecture review, preserving context can still be worth the additional usage.

Choosing the right approach for each use case is the key to balancing quality and cost.

Summary

Claude Code's batch processing is built on two pillars: /batch and headless mode (claude -p).

/batch enables safe parallel execution of framework migrations and naming convention unification through Git Worktree agent isolation and automatic PR creation. Headless mode handles CI/CD pipeline and shell script integration, serving as the foundation for embedding AI reviews and automated analysis into existing workflows.

Because /batch behavior can change, use the current Commands and Run agents in parallel pages as the source of truth rather than relying on a fixed version table.12

  1. Commands — Claude Code Docs — Current definitions of bundled skills including /batch and /simplify. ↩↩↩

  2. Run agents in parallel — Claude Code Docs — Current /batch planning, worktree, agent, and pull-request flow. ↩↩

  3. Claude Code CLI Reference (Official) — Specifications for --print, --allowedTools, --append-system-prompt, and other flags. ↩