ComeOnOliver/skillshub / skills/aiskillstore/marketplace/0xdarkmatter/claude-code-headless
claude-code-headless
VerifiedRun Claude Code programmatically without interactive UI. Triggers on: headless, CLI automation, --print, output-format, stream-json, CI/CD, scripting.
Claude Code Headless Mode
Run Claude Code from scripts without interactive UI.
Quick Start
# 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)
claude -p "Hello"
# Outputs: Human-readable response
JSON
claude -p "Hello" --output-format 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
claude -p "Hello" --output-format stream-json
# Real-time JSONL output for each message
Common Patterns
Script with tool restrictions
claude -p "Analyze the codebase" \
--allowedTools "Read,Grep,Glob" \
--disallowedTools "Write,Edit,Bash"
CI/CD integration
claude -p "Review this PR diff" \
--permission-mode acceptEdits \
--output-format json \
--append-system-prompt "Focus on security issues"
Multi-turn automation
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
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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |