Claude code headless

Skill aiskillstore/marketplace/skills/0xdarkmatter/claude-code-headless

Security-audited skills for Claude, Codex & Claude Code. One-click install, quality verified.

Install

npx -y skills add aiskillstore/marketplace --skill claude-code-headless

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.

What its author says it does

Copied from the file, not written here

Run Claude Code programmatically without interactive UI. Triggers on: headless, CLI automation, --print, output-format, stream-json, CI/CD, scripting.

SKILL.md

3.2 KB, 814 tokens by cl100k_base, as published. Nobody here has run it

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