Headless Runner

Run Claude Code programmatically from scripts, CI/CD pipelines, and autonomous agent workflows. Headless mode automatically loads all project configuration (.claude/ directory), giving you full access to skills, agents, hooks, and commands.

Quick Start

Most common usage:

bash

# Basic headless invocation (from project directory)
claude -p "Your prompt here"

# With JSON output for programmatic parsing
claude -p "Run eval baseline for v0.3.14" --output-format json

# Control tool access
claude -p "Analyze failures" --allowedTools "Bash,Read,Grep"

# Multi-turn conversation
claude -p "Start task" --output-format json > result.json
SESSION_ID=$(jq -r '.session_id' result.json)
claude --resume $SESSION_ID "Continue with next step"

What gets loaded automatically:

✅ .claude/settings.json and .claude/settings.local.json
✅ .claude/agents/ (all project agents)
✅ .claude/skills/ (all project skills)
✅ Hooks configured in settings
✅ Slash commands from .claude/commands/
✅ CLAUDE.md project instructions

When to Use This Skill

Invoke this skill when user asks about:

"How do I run Claude headless?"
"Can I automate Claude workflows?"
"How to use Claude in CI/CD?"
"Programmatic Claude execution"
"Script Claude commands"
"Agent-to-agent communication"
"Automated eval runs"
"Scheduled Claude tasks"

Core Commands

Basic Invocation

bash

# Text output (default)
claude -p "Prompt here"

# JSON output with metadata
claude -p "Prompt here" --output-format json
# Returns: {session_id, result, cost, duration, ...}

# Streaming JSON (for long-running tasks)
claude -p "Prompt here" --output-format stream-json

Tool Permissions

bash

# Allow specific tools
claude -p "Task" --allowedTools "Bash,Read,Write"

# Allow all tools (use with caution)
claude -p "Task" --allowedTools "*"

# Permission mode for edits
claude -p "Task" --permission-mode acceptEdits

Multi-Turn Conversations

bash

# Resume specific session
claude --resume SESSION_ID "Continue task"

# Continue most recent session
claude --continue "Next instruction"

# Extract session ID from JSON output
SESSION_ID=$(claude -p "Start" --output-format json | jq -r '.session_id')
claude --resume $SESSION_ID "Continue"

Common Use Cases

1. CI/CD Integration

bash

# .github/workflows/eval-baseline.yml
- name: Run eval baseline
  run: |
    claude -p "Use eval-orchestrator agent to run baseline for ${{ github.ref_name }}" \
      --output-format json \
      --allowedTools "Bash,Read,Write" \
      > eval_result.json

- name: Check for failures
  run: |
    FAILURES=$(jq -r '.failures' eval_result.json)
    if [ "$FAILURES" -gt 0 ]; then
      echo "::error::Eval baseline has $FAILURES failures"
      exit 1
    fi

2. Scheduled Analysis

bash

#!/bin/bash
# cron_daily_check.sh - Run via cron daily

cd /path/to/project

# Check agent inbox
claude -p "Use agent-inbox skill to check for unread messages" \
  --output-format json > inbox.json

# If messages exist, notify
UNREAD=$(jq -r '.unreadCount' inbox.json)
if [ "$UNREAD" -gt 0 ]; then
  echo "Found $UNREAD unread agent messages"
  # Send notification, create issue, etc.
fi

3. Agent-to-Agent Workflows

bash

#!/bin/bash
# autonomous_sprint_cycle.sh

# Agent A: Create design doc
claude -p "Use design-doc-creator to document feature X" \
  --output-format json > design.json

DESIGN_DOC=$(jq -r '.artifactPath' design.json)

# Agent B: Plan sprint from design
claude -p "Use sprint-planner to create plan from $DESIGN_DOC" \
  --output-format json > plan.json

PLAN_FILE=$(jq -r '.planPath' plan.json)

# Agent C: Execute sprint
claude -p "Use sprint-executor to execute $PLAN_FILE" \
  --output-format json > execution.json

4. Automated Testing

bash

#!/bin/bash
# test_agent_quality.sh

# Run eval with specific model
claude -p "Use eval-orchestrator: run suite with gpt5-mini only" \
  --output-format json > results.json

# Parse results
SUCCESS_RATE=$(jq -r '.successRate' results.json)

# Assert quality threshold
if (( $(echo "$SUCCESS_RATE < 0.75" | bc -l) )); then
  echo "Agent quality below threshold: $SUCCESS_RATE"
  exit 1
fi

Available Scripts

`scripts/test_headless.sh`

Test headless mode works correctly with project configuration.

Usage:

bash

.claude/skills/headless-runner/scripts/test_headless.sh

What it tests:

✓ claude command is available
✓ Project configuration loads (.claude/ directory)
✓ Skills are accessible
✓ Agents are accessible
✓ JSON output parses correctly
✓ Multi-turn sessions work

`scripts/run_with_retry.sh <prompt> [max_retries]`

Run headless command with automatic retry on failure.

Usage:

bash

.claude/skills/headless-runner/scripts/run_with_retry.sh "Run eval baseline" 3

Features:

Retries on transient failures
Exponential backoff
JSON output preserved
Exit codes: 0 (success), 1 (permanent failure), 2 (retries exhausted)

Workflow Patterns

Pattern 1: Single Command

Use for: Simple, one-off tasks

bash

claude -p "Generate changelog from git log since v0.3.13"

Pattern 2: Sequential Pipeline

Use for: Multi-step workflows where each step depends on previous

bash

#!/bin/bash
set -euo pipefail

# Step 1
claude -p "Step 1" --output-format json > step1.json
ARTIFACT1=$(jq -r '.artifact' step1.json)

# Step 2 (uses Step 1 output)
claude -p "Step 2 using $ARTIFACT1" --output-format json > step2.json
ARTIFACT2=$(jq -r '.artifact' step2.json)

# Step 3
claude -p "Step 3 using $ARTIFACT2"

Pattern 3: Conversation Session

Use for: Multi-turn tasks that need context

bash

#!/bin/bash

# Start conversation
RESULT=$(claude -p "Analyze codebase for tech debt" --output-format json)
SESSION_ID=$(echo "$RESULT" | jq -r '.session_id')

# Continue conversation with context
claude --resume $SESSION_ID "Focus on files over 800 lines"
claude --resume $SESSION_ID "Generate refactoring plan"
claude --resume $SESSION_ID "Estimate effort for top 3 items"

Pattern 4: Parallel Execution

Use for: Independent tasks that can run concurrently

bash

#!/bin/bash

# Start multiple tasks in parallel
claude -p "Task A" --output-format json > taskA.json &
PID_A=$!

claude -p "Task B" --output-format json > taskB.json &
PID_B=$!

claude -p "Task C" --output-format json > taskC.json &
PID_C=$!

# Wait for all to complete
wait $PID_A $PID_B $PID_C

# Aggregate results
jq -s '{taskA: .[0], taskB: .[1], taskC: .[2]}' taskA.json taskB.json taskC.json

Quick Tips

Output formats:

--output-format text (default) - Human-readable
--output-format json - For automation (includes session_id, status, cost)
--output-format stream-json - For real-time progress

Configuration:

Runs from project directory → auto-loads .claude/ config
No special flags needed for skills/agents/commands

Error handling:

Always check exit codes: if ! claude -p "..." ; then ...
Validate JSON: echo "$RESULT" | jq -e '.status == "success"'
Use retry with backoff (see run_with_retry.sh script)

Tool permissions:

Analysis: --allowedTools "Read,Grep,Glob"
Testing: --allowedTools "Bash,Read"
Development: --allowedTools "Bash,Read,Write,Edit"

For complete details, see CLI Reference and Troubleshooting.

AILANG Agent Integration

Build autonomous agents using headless Claude + AILANG messaging:

For complete autonomous agent patterns (task claiming, handoffs, error handling), see:

resources/agent_workflows.md - Autonomous agent patterns with messaging
agent-inbox skill - Inbox management and message format reference

Quick example:

bash

# Agent checks inbox for tasks
MESSAGES=$(ailang agent inbox --unread-only my-agent)
MESSAGE_ID=$(echo "$MESSAGES" | grep "ID:" | head -1 | awk '{print $2}')

# Claim task
ailang agent ack $MESSAGE_ID

# Process with headless Claude
RESULT=$(claude -p "Process task from inbox" --output-format json)

# On success: keep ack, send result
if [ "$(echo "$RESULT" | jq -r '.status')" = "success" ]; then
  ailang agent send --to-user --from "my-agent" '{"status": "complete"}'
else
  # On failure: return to queue
  ailang agent unack $MESSAGE_ID
fi

Resources

Agent Workflows (NEW!)

See resources/agent_workflows.md for autonomous agent patterns with AILANG messaging system.

CLI Reference

See resources/cli_reference.md for complete CLI flag documentation.

Examples

See resources/examples.md for comprehensive workflow examples.

Troubleshooting

See resources/troubleshooting.md for common issues and solutions.

Progressive Disclosure

This skill loads information progressively:

Always loaded: This SKILL.md file (YAML frontmatter + core workflows)
Execute as needed: Scripts in scripts/ directory
Load on demand: resources/ (detailed CLI reference, examples, troubleshooting)

Notes

Requires: Claude Code CLI installed and in PATH
Context window: Be mindful of token limits for large prompts
Costs: Track with --output-format json → .cost field
Concurrency: Multiple headless sessions can run in parallel
State: Each invocation is stateless unless using --resume

Search AI Tools

Headless Runner

Install this agent skill to your Project

SKILL.md

Headless Runner

Quick Start

When to Use This Skill

Core Commands

Basic Invocation

Tool Permissions

Multi-Turn Conversations

Common Use Cases

1. CI/CD Integration

2. Scheduled Analysis

3. Agent-to-Agent Workflows

4. Automated Testing

Available Scripts

`scripts/test_headless.sh`

`scripts/run_with_retry.sh <prompt> [max_retries]`

Workflow Patterns

Pattern 1: Single Command

Pattern 2: Sequential Pipeline

Pattern 3: Conversation Session

Pattern 4: Parallel Execution

Quick Tips

AILANG Agent Integration

Resources

Agent Workflows (NEW!)

CLI Reference

Examples

Troubleshooting

Progressive Disclosure

Notes