claude-code-headless
Run Claude Code programmatically without interactive UI. Triggers on: headless, CLI automation, --print, output-format, stream-json, CI/CD, scripting.
Best use case
claude-code-headless is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Run Claude Code programmatically without interactive UI. Triggers on: headless, CLI automation, --print, output-format, stream-json, CI/CD, scripting.
Teams using claude-code-headless should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/claude-code-headless/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How claude-code-headless Compares
| Feature / Agent | claude-code-headless | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Run Claude Code programmatically without interactive UI. Triggers on: headless, CLI automation, --print, output-format, stream-json, CI/CD, scripting.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
Related Guides
Best AI Skills for Claude
Explore the best AI skills for Claude and Claude Code across coding, research, workflow automation, documentation, and agent operations.
ChatGPT vs Claude for Agent Skills
Compare ChatGPT and Claude for AI agent skills across coding, writing, research, and reusable workflow execution.
SKILL.md Source
# Claude Code Headless Mode
Run Claude Code from scripts without interactive UI.
## Quick Start
```bash
# Basic headless execution
claude -p "Explain this code" --allowedTools "Read,Grep"
# JSON output for parsing
claude -p "List files" --output-format json
# Continue conversation
claude -p "Start analysis" --output-format json > result.json
session=$(jq -r '.session_id' result.json)
claude --resume "$session" "Now fix the issues"
```
## Essential CLI Options
| Flag | Description |
|------|-------------|
| `-p`, `--print` | Non-interactive (headless) mode |
| `--output-format` | text, json, stream-json |
| `-r`, `--resume` | Resume by session ID |
| `-c`, `--continue` | Continue most recent session |
| `--allowedTools` | Comma-separated allowed tools |
| `--disallowedTools` | Comma-separated denied tools |
| `--mcp-config` | Path to MCP server config JSON |
| `--verbose` | Enable verbose logging |
| `--append-system-prompt` | Add to system prompt |
## Permission Modes
| Mode | Flag | Effect |
|------|------|--------|
| Default | (none) | Prompt for permissions |
| Accept edits | `--permission-mode acceptEdits` | Auto-accept file changes |
| Bypass | `--permission-mode bypassPermissions` | Skip all prompts |
## Output Formats
### Text (default)
```bash
claude -p "Hello"
# Outputs: Human-readable response
```
### JSON
```bash
claude -p "Hello" --output-format json
```
```json
{
"type": "result",
"subtype": "success",
"result": "Hello! How can I help?",
"session_id": "abc123",
"total_cost_usd": 0.001,
"duration_ms": 1234,
"num_turns": 1
}
```
### Stream-JSON
```bash
claude -p "Hello" --output-format stream-json
# Real-time JSONL output for each message
```
## Common Patterns
### Script with tool restrictions
```bash
claude -p "Analyze the codebase" \
--allowedTools "Read,Grep,Glob" \
--disallowedTools "Write,Edit,Bash"
```
### CI/CD integration
```bash
claude -p "Review this PR diff" \
--permission-mode acceptEdits \
--output-format json \
--append-system-prompt "Focus on security issues"
```
### Multi-turn automation
```bash
session=$(claude -p "Start task" --output-format json | jq -r '.session_id')
claude --resume "$session" "Continue with step 2"
claude --resume "$session" "Finalize and report"
```
## Error Handling
```bash
result=$(claude -p "Task" --output-format json)
if [[ $(echo "$result" | jq -r '.is_error') == "true" ]]; then
echo "Error: $(echo "$result" | jq -r '.result')" >&2
exit 1
fi
```
## Official Documentation
- https://code.claude.com/docs/en/headless - Headless mode reference
- https://code.claude.com/docs/en/settings - Settings and permissions
## Additional Resources
- `./references/cli-options.md` - Complete CLI flag reference
- `./references/output-formats.md` - Output format schemas
- `./references/integration-patterns.md` - CI/CD and scripting examples
---
**See Also:** `claude-code-hooks` for automation events, `claude-code-debug` for troubleshooting