headless-runner

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:

# 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

# 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

# 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

# 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

# .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

#!/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

#!/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

#!/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:

.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:

.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

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

#!/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

#!/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

#!/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:

# 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:

1. Always loaded: This SKILL.md file (YAML frontmatter + core workflows)
2. Execute as needed: Scripts in scripts/ directory
3. 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