headless-testing

Overview

Claude Code can run in “headless” (non-interactive) mode using the -p/--print flag. This is essential for testing agents during development since agent changes require a session restart.

Task 2 Confirmation: ✅ Verified

Claude can run in headless mode via CLI:

claude -p "What is 2+2?"
# Output: 4

Basic Usage

Simple Prompt

claude -p "Your prompt here"

The response is printed to stdout and the command exits immediately.

Advanced Options

Output Formats

Text (default)

claude -p "Explain recursion"

JSON

claude -p "List three colors" --output-format json

Streaming JSON

claude -p "Write a story" --output-format stream-json

Model Selection

# Use Haiku for fast, simple tasks
claude -p "Fix this typo: recieve" --model haiku

# Use Opus for complex reasoning
claude -p "Analyze this architecture" --model opus

# Use Sonnet (default, balanced)
claude -p "Review this code" --model sonnet

Tool Control

Restrict to specific tools:

claude -p "Read file.txt" --tools "Read,Grep"

Disable all tools:

claude -p "Just answer this question" --tools ""

Allow specific tool patterns:

claude -p "Use git" --allowed-tools "Bash(git:*)"

Deny specific tools:

claude -p "No file edits" --disallowed-tools "Edit,Write"

System Prompts

Add custom system prompt:

claude -p "Explain OOP" --system-prompt "You are a teacher explaining to beginners"

Append to default system prompt:

claude -p "Review code" --append-system-prompt "Focus on security issues"

Conversation Continuity

Continue most recent conversation:

claude -p "Tell me a joke"
claude -p "Explain it" --continue

Resume specific session:

claude -p "Continue working" --resume <session-id>

Fork conversation (new session ID):

claude -p "Try different approach" --resume <session-id> --fork-session

Permission Modes

# Auto-accept all edits
claude -p "Fix bugs" --permission-mode acceptEdits

# Skip all permissions (use in trusted sandboxes only)
claude -p "Make changes" --permission-mode bypassPermissions

# Don't ask for permissions
claude -p "Just tell me" --permission-mode dontAsk

# Plan mode
claude -p "Plan implementation" --permission-mode plan

MCP Configuration

Load specific MCP config:

claude -p "Query database" --mcp-config ./custom-mcp.json

Use only specified config:

claude -p "Use only this MCP" --mcp-config ./mcp.json --strict-mcp-config

Settings Override

Load settings from file:

claude -p "Run with custom settings" --settings ./test-settings.json

Load settings from JSON string:

claude -p "Test" --settings '{"verbose":true}'

Agent Development Workflow

The Problem

Agent files (.claude/agents/*.md) are loaded when Claude Code starts. Changes to agent files require restarting the session to take effect in interactive mode.

The Solution: Headless Testing

You can test agent changes without restarting the interactive session:

# 1. Edit your agent file
vim .claude/agents/my-agent.md

# 2. Test in headless mode (loads fresh agent definitions)
claude -p "Test my agent functionality"

# 3. Iterate rapidly
vim .claude/agents/my-agent.md
claude -p "Test again with different input"

# 4. Once satisfied, restart interactive session for production use

Testing Workflow Example

# Create a test agent
cat > .claude/agents/test-reviewer.md << 'EOF'
---
name: test-reviewer
description: Reviews code for test coverage issues
tools: Read, Grep
model: haiku
---

You review code and identify missing test coverage.
Focus on functions without corresponding tests.
EOF

# Test the agent in headless mode
claude -p "Review test coverage in src/"

# Refine the agent based on results
vim .claude/agents/test-reviewer.md

# Test again
claude -p "Review test coverage in src/ and suggest specific test cases"

# Continue iterating...

Practical Testing Patterns

Quick Validation

# Test that agent loads without errors
claude -p "Hello" --output-format json

Agent-Specific Testing

# Test agent with typical task
claude -p "Review this file for security issues" --tools "Read,Grep"

Output Verification

# Capture output for analysis
claude -p "Generate report" --output-format json > output.json
cat output.json | jq '.response'

Integration Testing

# Test with specific MCP servers
claude -p "Query temporal bridge" --mcp-config test-mcp.json

Performance Testing

# Time the execution
time claude -p "Complex analysis task"

Regression Testing

# Save baseline output
claude -p "Test case 1" > baseline.txt

# After changes, compare
claude -p "Test case 1" > current.txt
diff baseline.txt current.txt

Piping and Scripting

Input from stdin

cat prompt.txt | claude -p

Pipe to other tools

claude -p "List files" | grep ".ts$"

Scripted testing

#!/bin/bash
for test_case in test_cases/*.txt; do
  echo "Testing: $test_case"
  claude -p "$(cat $test_case)" --output-format json > "results/$(basename $test_case).json"
done

JSON processing

claude -p "Generate JSON data" --output-format json | jq '.result'

Environment Setup for Testing

Test Configuration File

{
  "model": "haiku",
  "verbose": false,
  "tools": ["Read", "Grep"],
  "permissionMode": "bypassPermissions"
}

Usage:

claude -p "Test" --settings test-config.json

Test MCP Configuration

{
  "mcpServers": {
    "test-server": {
      "command": "node",
      "args": ["test-mcp-server.js"]
    }
  }
}

Usage:

claude -p "Test MCP" --mcp-config test-mcp.json

Directory Isolation

# Test in isolated directory
mkdir test-env
cd test-env
cp ../.claude/agents/my-agent.md .claude/agents/
claude -p "Test in isolation"
cd ..

Debugging

Enable debug mode

# All debug output
claude -p "Debug this" --debug

# Specific categories
claude -p "Debug API" --debug api

# Multiple categories
claude -p "Debug" --debug "api,hooks"

# Exclude categories
claude -p "Debug" --debug "!statsig,!file"

Verbose output

claude -p "Show details" --verbose

MCP debugging

claude -p "Test MCP" --debug mcp

Best Practices

1. Fast Iteration

Use headless mode for rapid agent development:

Edit agent
Test in headless mode
Iterate quickly
Only restart interactive session when satisfied

2. Use Appropriate Models

haiku: Fast testing of simple agent logic
sonnet: Realistic testing of balanced agents
opus: Test complex reasoning capabilities

3. Isolate Tests

Use specific tool restrictions
Test one capability at a time
Use minimal prompts for focused testing

4. Capture Results

Save outputs for comparison
Use JSON format for structured testing
Build regression test suites

5. Security

Use --dangerously-skip-permissions only in sandboxes
Test permission handling separately
Verify tool restrictions work as expected

Common Issues

Agent Not Found

Problem: Agent changes not reflected Solution: Headless mode loads fresh agent definitions - this shouldn’t happen

Tool Access Denied

Problem: Agent can’t use required tools Solution: Add tools to agent tools: field or use --tools flag in testing

Session Conflicts

Problem: Headless and interactive sessions conflict Solution: Use --session-id to separate test sessions

Output Format Issues

Problem: Can’t parse output Solution: Use --output-format json for structured output

Summary

Headless mode (claude -p) is a powerful tool for agent development:

✅ Confirmed working: Basic functionality verified
⚡ Fast iteration: No session restarts needed for testing
🔧 Flexible: Many configuration options
📊 Scriptable: Easy to automate testing
🔒 Isolated: Test without affecting interactive sessions

Use it to rapidly develop and test agents before deploying them in interactive sessions.