claude-code-headless
Run Claude Code programmatically without interactive UI. Triggers on: headless, CLI automation, --print, output-format, stream-json, CI/CD, scripting.
Install / Use
npx skills add aiskillstore/marketplace --skill claude-code-headlessInstalls into whichever agent you are using.
SKILL.md
Installable skill definition
Quality Score
Category
AutomationSupported Platforms
Tags
Our assessment of claude-code-headless
claude-code-headless scores 87/100 on our quality scale, 1721st of 2,768 Automation skills we index.
Its SKILL.md is 3.2 KB long, well organised into 20 sections with 9 code examples: a solid amount of guidance for an agent.
It has 428 GitHub stars, a meaningful sign that others use it.
Maintenance, license and trust
- The repository was last updated about 2 months ago, so claude-code-headless is actively maintained.
- Our last check on 2026-11-02 found the source still online.
- No license is declared. By default that means all rights are reserved: you can read it, but reusing or redistributing it is not clearly permitted. Ask the author before building on it commercially.
- Its trust signals score 88/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
Safety scan
ReviewOur scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review judged it risky: The skill file documents and gives runnable examples using --permission-mode acceptEdits and --permission-mode bypassPermissions, which skip or auto-approve permission prompts.
AI review: risky
- The skill file documents and gives runnable examples using --permission-mode acceptEdits and --permission-mode bypassPermissions, which skip or auto-approve permission prompts.
- As a skill/rules file, these examples are instructions the agent may follow, directly weakening the user's permission safeguards.
- The content is otherwise a legitimate headless/CI automation guide for Claude Code, so it is not outright malicious.
AI review by kimi-k2.7-code on 2026-10-07. Automated pattern scan on 2026-10-07. It catches known dangerous patterns, not every risk — read a skill before letting an agent act on it.
claude-code-headless compared with similar skills
All 4 of these similar skills score higher than claude-code-headless; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| claude-code-headless (this skill)by aiskillstore | 87 | 428 | 55d ago | SKILL.md |
| Agent-Reachby Panniantong | 100 | 113.0k | 10d ago | CLAUDE.md |
| rufloby ruvnet | 100 | 82.0k | today | CLAUDE.md |
| Claude-Code-Game-Studiosby Donchitos | 100 | 40.1k | 9d ago | CLAUDE.md |
| Scraplingby D4Vinci | 100 | 104.2k | 1d ago | MCP Server |
Frequently asked questions
- How do I install claude-code-headless?
- Run
npx skills add aiskillstore/marketplace --skill claude-code-headless. The install tabs above show the steps for each supported agent. - Which AI agents does claude-code-headless work with?
- It is written for Claude Code, as a SKILL.md file. Other agents that read the same format can often use it too.
- Is claude-code-headless safe to use?
- Our scan of the whole file found no instruction hijacking, hidden characters, credential access, data exfiltration or destructive commands. An AI review judged it risky: The skill file documents and gives runnable examples using --permission-mode acceptEdits and --permission-mode bypassPermissions, which skip or auto-approve permission prompts. It declares no license and scores 88/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is claude-code-headless still maintained?
- The repository was last updated about 2 months ago, so claude-code-headless is actively maintained.
Skill content
View source on GitHubname: claude-code-headless description: "Run Claude Code programmatically without interactive UI. Triggers on: headless, CLI automation, --print, output-format, stream-json, CI/CD, scripting." compatibility: "Claude Code CLI" allowed-tools: "Bash Read" depends-on: [] related-skills: [claude-code-hooks, claude-code-debug]
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
Agent-Reach
113.0kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
ruflo
82.0k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
Claude-Code-Game-Studios
40.1kTurn Claude Code into a full game dev studio — 49 AI agents, 75 workflow skills, and a complete coordination system mirroring real studio hierarchy.
Scrapling
104.2k🕷️ The BEST Web Scraping framework that handles everything from a single request to a full-scale crawl! Don't be shy, join here: https://discord.gg/EMgGbDceNQ and follow here for daily tips and tricks: https://x.com/Scrapling_dev
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
