148 lines
3.9 KiB
Markdown
148 lines
3.9 KiB
Markdown
---
|
|
name: headless
|
|
description: How to run Claude Code in headless mode for automation, scripting, and CI/CD integration. Use when user asks about non-interactive mode, automation, scripting, or programmatic usage.
|
|
---
|
|
|
|
# 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 severity assessment using allowed tools and MCP configuration for monitoring integrations.
|
|
|
|
### Security Review
|
|
Audit pull request diffs for vulnerabilities and compliance issues using Read and WebSearch tools.
|
|
|
|
### Legal Assistant
|
|
Multi-step document review maintaining session context across separate requests.
|
|
|
|
## Best Practices
|
|
|
|
- Use JSON output for programmatic parsing and integration
|
|
- Parse results with tools like `jq` for data extraction
|
|
- Handle errors by checking exit codes and stderr
|
|
- Maintain session context for multi-turn workflows
|
|
- Implement timeouts for long-running operations
|
|
- Respect rate limits with delays between requests
|
|
- Leverage session management for maintaining conversation state
|
|
|
|
## Example: Automated Code Review
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
# Review PR changes in headless mode
|
|
|
|
RESULT=$(claude -p "Review changes in git diff for security issues" \
|
|
--allowedTools "Bash,Read,Grep" \
|
|
--output-format json \
|
|
--permission-mode acceptAll)
|
|
|
|
# Parse result
|
|
echo "$RESULT" | jq -r '.result'
|
|
|
|
# Check exit code
|
|
if [ $? -ne 0 ]; then
|
|
echo "Review failed"
|
|
exit 1
|
|
fi
|
|
```
|
|
|
|
## Example: CI/CD Integration
|
|
|
|
```bash
|
|
# In .gitlab-ci.yml or GitHub Actions
|
|
claude -p "Run tests and fix any failures" \
|
|
--allowedTools "Bash,Read,Edit,Write" \
|
|
--max-turns 10 \
|
|
--output-format json
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
Check exit codes and parse error messages:
|
|
- Exit code 0: Success
|
|
- Non-zero: Error occurred (check stderr)
|
|
|
|
```bash
|
|
if ! claude -p "task" 2>error.log; then
|
|
echo "Error: $(cat error.log)"
|
|
exit 1
|
|
fi
|
|
```
|
|
|
|
## Session Management
|
|
|
|
Save session IDs for continuation:
|
|
```bash
|
|
# First run
|
|
RESULT=$(claude -p "Start analysis" --output-format json)
|
|
SESSION_ID=$(echo "$RESULT" | jq -r '.session_id')
|
|
|
|
# Continue later
|
|
claude --resume "$SESSION_ID" "Continue analysis"
|
|
```
|