CtrlK
BlogDocsLog inGet started
Tessl Logo

claude-code-headless

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

Invalid
This skill can't be scored yet
Validation errors are blocking scoring. Review and fix them to unlock Quality, Impact and Security scores. See what needs fixing →
SKILL.md
Quality
Evals
Security

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

FlagDescription
-p, --printNon-interactive (headless) mode
--output-formattext, json, stream-json
-r, --resumeResume by session ID
-c, --continueContinue most recent session
--allowedToolsComma-separated allowed tools
--disallowedToolsComma-separated denied tools
--mcp-configPath to MCP server config JSON
--verboseEnable verbose logging
--append-system-promptAdd to system prompt

Permission Modes

ModeFlagEffect
Default(none)Prompt for permissions
Accept edits--permission-mode acceptEditsAuto-accept file changes
Bypass--permission-mode bypassPermissionsSkip 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

Repository
NeverSight/skills_feed
Commit

5342bca

Last updated
Created

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.

Claim skill