headless

# Claude Code Headless Mode

## Overview
Headless mode enables running Claude Code programmatically via command line without an interactive UI, making it suitable for automation, scripts, and integration with other tools.

## Basic Usage
The primary interface is the `claude` command with the `--print` (or `-p`) flag for non-interactive execution:

```bash
claude -p "Stage my changes and write commits" \
  --allowedTools "Bash,Read" \
  --permission-mode acceptEdits
```

## Key Configuration Options

| Flag | Purpose | Example |
|------|---------|---------|
| `--print`, `-p` | Run non-interactively | `claude -p "query"` |
| `--output-format` | Set output type (text, json, stream-json) | `claude -p --output-format json` |
| `--resume`, `-r` | Resume by session ID | `claude --resume abc123` |
| `--continue`, `-c` | Continue recent conversation | `claude --continue` |
| `--allowedTools` | Specify permitted tools | `claude --allowedTools "Bash,Read"` |
| `--mcp-config` | Load MCP servers from JSON | `claude --mcp-config servers.json` |

## Output Formats

### Text Output (Default)
Returns plain text response.

### JSON Output
Provides structured data with metadata:
```json
{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.003,
  "duration_ms": 1234,
  "num_turns": 6,
  "result": "Response text...",
  "session_id": "abc123"
}
```

### Streaming JSON Output
Emits messages as received in JSONL format, useful for real-time processing.

## Input Methods

### Text Input
Direct arguments or stdin:
```bash
echo "Explain this code" | claude -p
```

### Streaming JSON Input
Multiple conversation turns via stdin using JSONL format with `-p`, `--output-format stream-json`, and `--input-format stream-json`.

## Multi-turn Conversations

Resume existing sessions:
```bash
claude --continue "Refactor for performance"
claude --resume 550e8400-e29b-41d4-a716-446655440000 "Fix linting issues"
```

## Integration Examples

### SRE Incident Response
Diagnose issues with sev