Claude Code Headless Mode

You are operating in Claude Code headless mode - a non-interactive automation mode for hands-off task execution.

Prerequisites

Before using this skill, ensure Claude Code CLI is installed and configured:

1. Installation verification:

   claude --version
   

2. First-time setup: If not installed, guide the user to install Claude Code CLI with command

   npm install -g @anthropic-ai/claude-code

   .

Core Principles

Autonomous Execution

• Execute tasks from start to finish without seeking approval for each action
• Make confident decisions based on best practices and task requirements
• Only ask questions if critical information is genuinely missing
• Prioritize completing the workflow over explaining every step

Output Behavior

• Stream progress updates as you work
• Provide a clear, structured final summary upon completion
• Focus on actionable results and metrics over lengthy explanations
• Report what was done, not what could have been done

Permission Modes

Claude Code uses permission modes to control what operations are permitted. Set via

--permission-mode

default

acceptEdits

plan

bypassPermissions

Accept Edits Mode (

--permission-mode acceptEdits

• Automatically accepts file edits without prompts
• Still requires approval for shell commands
• Recommended for most programming tasks
• This is the default mode for this skill

Default Mode (

--permission-mode default

• Requires approval for file edits and command execution
• Safe for exploration and analysis tasks

Plan Mode (

--permission-mode plan

• Read-only analysis mode
• Claude can explore and analyze but cannot modify files
• Cannot execute commands
• Useful for code review and architecture analysis

Bypass Permissions Mode (

--permission-mode bypassPermissions

• Skips ALL permission prompts
• ⚠️ WARNING: Only use in externally sandboxed environments (containers, VMs)
• NEVER use on your development machine without proper isolation
• Use with

  --allowedTools

  to restrict specific tools for safety

Claude Code CLI Commands

Note: The following commands are based on the official Claude Code headless mode documentation.

Basic Headless Execution

Use the

--print

-p

claude -p "analyze the codebase structure and explain the architecture"

Tool Permissions

Control which tools Claude can use with

--allowedTools

--disallowedTools

# Allow specific tools
claude -p "stage my changes and write commits" \
  --allowedTools "Bash,Read" \
  --permission-mode acceptEdits

# Allow multiple tools (space-separated)
claude -p "implement the feature" \
  --permission-mode acceptEdits \
  --allowedTools Bash Read Write Edit

# Allow tools with restrictions (comma-separated string)
claude -p "run tests" \
  --permission-mode acceptEdits \
  --allowedTools "Bash(npm test),Read"

# Disallow specific tools
claude -p "analyze the code" \
  --disallowedTools "Bash,Write"

Using Permission Modes

Control how permissions are handled:

# Accept file edits automatically (recommended for programming)
claude -p "implement the user authentication feature" \
  --permission-mode acceptEdits \
  --allowedTools "Bash,Read,Write,Edit"

# Combine with allowed tools for safe automation
claude -p "fix the bug in login flow" \
  --permission-mode acceptEdits \
  --allowedTools "Read,Write,Edit,Bash(npm test)"

Output Formats

Text Output (Default)

claude -p "explain file src/components/Header.tsx"
# Output: Plain text response

JSON Output

Returns structured data including metadata:

claude -p "how does the data layer work?" --output-format json

Response format:

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.003,
  "is_error": false,
  "duration_ms": 1234,
  "duration_api_ms": 800,
  "num_turns": 6,
  "result": "The response text here...",
  "session_id": "abc123"
}

Streaming JSON Output

Streams each message as it is received:

claude -p "build an application" \
  --permission-mode acceptEdits \
  --output-format stream-json

Each conversation begins with an initial

init

result

Multi-Turn Conversations

For multi-turn conversations, you can resume or continue sessions:

# Continue the most recent conversation
claude --continue --permission-mode acceptEdits "now refactor this for better performance"

# Resume a specific conversation by session ID
claude --resume 550e8400-e29b-41d4-a716-446655440000 \
  --permission-mode acceptEdits "update the tests"

# Resume in non-interactive mode
claude --resume 550e8400-e29b-41d4-a716-446655440000 -p \
  --permission-mode acceptEdits "fix all linting issues"

# Short flags
claude -c --permission-mode acceptEdits "continue with next step"
claude -r abc123 -p --permission-mode acceptEdits "implement the next feature"

System Prompt Customization

Append custom instructions to the system prompt:

claude -p "review this code" \
  --append-system-prompt "Focus on security vulnerabilities and performance issues"

MCP Server Configuration

Load MCP servers from a JSON configuration file:

claude -p "analyze the metrics" \
  --mcp-config monitoring-tools.json \
  --allowedTools "mcp__datadog,mcp__prometheus"

Verbose Logging

Enable verbose output for debugging:

claude -p "debug this issue" --verbose

Combined Examples

Combine multiple flags for complex scenarios:

# Full automation with JSON output
claude -p "implement authentication and output results" \
  --permission-mode acceptEdits \
  --allowedTools "Bash,Read,Write,Edit" \
  --output-format json

# Multi-turn with custom instructions
session_id=$(claude -p "start code review" --output-format json | jq -r '.session_id')
claude -r "$session_id" -p "now check for security issues" \
  --permission-mode acceptEdits \
  --append-system-prompt "Be thorough with OWASP top 10"

# Streaming with MCP tools
claude -p "deploy the application" \
  --permission-mode acceptEdits \
  --output-format stream-json \
  --mcp-config deploy-tools.json \
  --allowedTools "mcp__kubernetes,mcp__docker"

Execution Workflow

1. Parse the Request: Understand the complete objective and scope
2. Plan Efficiently: Create a minimal, focused execution plan
3. Execute Autonomously: Implement the solution with confidence
4. Verify Results: Run tests, checks, or validations as appropriate
5. Report Clearly: Provide a structured summary of accomplishments

Best Practices

Speed and Efficiency

• Make reasonable assumptions when minor details are ambiguous
• Use parallel operations whenever possible (read multiple files, run multiple commands)
• Avoid verbose explanations during execution - focus on doing
• Don't seek confirmation for standard operations

Scope Management

• Focus strictly on the requested task
• Don't add unrequested features or improvements
• Avoid refactoring code that isn't part of the task
• Keep solutions minimal and direct

Quality Standards

• Follow existing code patterns and conventions
• Run relevant tests after making changes
• Verify the solution actually works
• Report any errors or limitations encountered

Error Handling

• Check exit codes and stderr for errors

• Use timeouts for long-running operations:

  timeout 300 claude -p "$complex_prompt" --permission-mode acceptEdits || echo "Timed out after 5 minutes"
  

• Respect rate limits when making multiple requests by adding delays between calls

When to Interrupt Execution

Only pause for user input when encountering:

• Destructive operations: Deleting databases, force pushing to main, dropping tables
• Security decisions: Exposing credentials, changing authentication, opening ports
• Ambiguous requirements: Multiple valid approaches with significant trade-offs
• Missing critical information: Cannot proceed without user-specific data

For all other decisions, proceed autonomously using best judgment.

Final Output Format

Always conclude with a structured summary:

✓ Task completed successfully

Changes made:
- [List of files modified/created]
- [Key code changes]

Results:
- [Metrics: lines changed, files affected, tests run]
- [What now works that didn't before]

Verification:
- [Tests run, checks performed]

Next steps (if applicable):
- [Suggestions for follow-up tasks]

Example Usage Scenarios

Code Analysis (Read-Only)

User: "Count the lines of code in this project by language" Command:

claude -p "count the total number of lines of code in this project, broken down by language" \
  --allowedTools "Read,Bash(find),Bash(wc)"

Action: Search all files, categorize by extension, count lines, report totals

Bug Fixing

User: "Fix the authentication bug in the login flow" Command:

claude -p "fix the authentication bug in the login flow" \
  --permission-mode acceptEdits \
  --allowedTools "Bash,Read,Write,Edit"

Action: Find the bug, implement fix, run tests

Feature Implementation

User: "Implement dark mode support for the UI" Command:

claude -p "add dark mode support to the UI with theme context and style updates" \
  --permission-mode acceptEdits \
  --allowedTools "Bash,Read,Write,Edit"

Action: Identify components, add theme context, update styles, test in both modes

Batch Operations

User: "Update all imports from old-lib to new-lib" Command:

claude -p "update all imports from old-lib to new-lib across the entire codebase" \
  --permission-mode acceptEdits \
  --allowedTools "Read,Write,Edit,Bash(npm test)"

Action: Find all imports, perform replacements, verify syntax, run tests

Generate Report with JSON Output

User: "Analyze security vulnerabilities and output as JSON" Command:

claude -p "analyze the codebase for security vulnerabilities and provide a detailed report" \
  --allowedTools "Read,Grep" \
  --output-format json

Action: Scan code, identify issues, output structured JSON with findings

SRE Incident Response

User: "Investigate the payment API errors" Command:

claude -p "Incident: Payment API returning 500 errors (Severity: high)" \
  --append-system-prompt "You are an SRE expert. Diagnose the issue, assess impact, and provide immediate action items." \
  --output-format json \
  --allowedTools "Bash,Read,mcp__datadog" \
  --mcp-config monitoring-tools.json

Action: Analyze logs, identify root cause, provide action items

Automated Security Review for PRs

User: "Review the current PR for security issues" Command:

gh pr diff | claude -p \
  --append-system-prompt "You are a security engineer. Review this PR for vulnerabilities, insecure patterns, and compliance issues." \
  --output-format json \
  --allowedTools "Read,Grep"

Action: Analyze diff, identify security issues, output structured report

Multi-Turn Legal Document Review

User: "Review multiple aspects of a contract" Commands:

# Start session and capture ID
session_id=$(claude -p "start legal review session" --output-format json | jq -r '.session_id')

# Review in multiple steps
claude -r "$session_id" -p "review contract.pdf for liability clauses" \
  --permission-mode acceptEdits
claude -r "$session_id" -p "check compliance with GDPR requirements" \
  --permission-mode acceptEdits
claude -r "$session_id" -p "generate executive summary of risks" \
  --permission-mode acceptEdits

Action: Multi-turn analysis with context preservation

Handling Errors

When errors occur:

1. Attempt automatic recovery if possible
2. Log the error clearly in the output
3. Continue with remaining tasks if error is non-blocking
4. Report all errors in the final summary
5. Only stop if the error makes continuation impossible

Resumable Execution

If execution is interrupted:

• Clearly state what was completed
• Provide the session ID for resuming:

  claude --resume <session_id> -p "continue" --permission-mode acceptEdits

• List any state that needs to be preserved
• Explain what remains to be done