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:

Installation verification:
bash
```
claude --version
```
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

flag:

Mode	Description
`default`	Standard behavior - prompts for permission on first use of each tool
`acceptEdits`	Automatically accepts file edit permissions for the session (Default for this skill)
`plan`	Plan Mode - Claude can analyze but not modify files or execute commands
`bypassPermissions`	Skips all permission prompts (requires safe environment - see warning below)

Accept Edits Mode (
--permission-mode acceptEdits
) - Default

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

(or

-p

) flag to run in non-interactive mode:

bash

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

Tool Permissions

Control which tools Claude can use with

--allowedTools

and

--disallowedTools

bash

# 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:

bash

# 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)

bash

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

JSON Output

Returns structured data including metadata:

bash

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

Response format:

json

{
  "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:

bash

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

Each conversation begins with an initial

init

system message, followed by user and assistant messages, followed by a final

result

system message with stats.

Multi-Turn Conversations

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

bash

# 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:

bash

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:

bash

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

Verbose Logging

Enable verbose output for debugging:

bash

claude -p "debug this issue" --verbose

Combined Examples

Combine multiple flags for complex scenarios:

bash

# 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

Parse the Request: Understand the complete objective and scope
Plan Efficiently: Create a minimal, focused execution plan
Execute Autonomously: Implement the solution with confidence
Verify Results: Run tests, checks, or validations as appropriate
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:

bash

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:

text

✓ 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:

bash

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:

bash

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:

bash

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:

bash

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:

bash

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:

bash

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:

bash

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:

bash

# 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:

Attempt automatic recovery if possible
Log the error clearly in the output
Continue with remaining tasks if error is non-blocking
Report all errors in the final summary
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

claude-skill

NPX Install

Tags

SKILL.md Content

Claude Code Headless Mode

Prerequisites

Core Principles

Autonomous Execution

Output Behavior

Permission Modes

Claude Code CLI Commands

Basic Headless Execution

Tool Permissions

Using Permission Modes

Output Formats

Text Output (Default)

JSON Output

Streaming JSON Output

Multi-Turn Conversations

System Prompt Customization

MCP Server Configuration

Verbose Logging

Combined Examples

Execution Workflow

Best Practices

Speed and Efficiency

Scope Management

Quality Standards

Error Handling

When to Interrupt Execution

Final Output Format

Example Usage Scenarios

Code Analysis (Read-Only)

Bug Fixing

Feature Implementation

Batch Operations

Generate Report with JSON Output

SRE Incident Response

Automated Security Review for PRs

Multi-Turn Legal Document Review

Handling Errors

Resumable Execution