headless-cli-agents

What this skill does

# Headless CLI Agents

## Overview

This skill enables the use of AI coding agents in non-interactive mode for automation scenarios. It provides command references, safety considerations, and practical examples for integrating AI agents into automated workflows.

## Quick Reference

| Agent | Basic Command | Automation Flag | Best For |
|-------|--------------|----------------|----------|
| Claude Code | `claude -p "prompt"` | Auto-approved by default | General coding tasks |
| OpenAI Codex | `codex exec "prompt"` | `--full-auto` | Complex refactoring |
| Google Gemini | `gemini -p "prompt"` | `--yolo` (if available) | Analysis tasks |
| OpenCode | `opencode -p "prompt"` | Auto-approved by default | Multi-provider support |
| Qwen Code | `qwen -p "prompt"` | `--yolo` | Local model support |
| Factory Droid | `droid exec "prompt"` | `--auto <level>` | Controlled automation |

## When to Use Headless Mode

## Core Concepts

### 1. Agent Selection

Choose the appropriate agent based on your requirements:

**Claude Code CLI** - Best for general-purpose coding with excellent code understanding
```bash
# Basic usage
claude -p "Review this code for security issues"

# With additional context
claude -p "Generate tests for authentication module" --add-dir ./tests
```

**OpenAI Codex CLI** - Best for complex refactoring and code transformation or a comprehensive research
```bash
# Automated refactoring
codex exec --full-auto "Refactor this module to use async/await"

# Outside git repos
codex exec --skip-git-repo-check --full-auto "Create API documentation"
```

**Google Gemini CLI** - Best for analysis and documentation tasks
```bash
# Analysis with structured output
gemini -p "Analyze codebase architecture" --output-format json

# Documentation generation
cat src/ | gemini -p "Generate comprehensive API documentation"
```

### 2. Safety and Autonomy Levels

Different agents provide varying levels of automation control:

**Important**: Always specify a timeout of at least 15 minutes for headless commands to prevent hanging

**Read-Only Mode (Safest)**
```bash
# Analysis without changes
droid exec "Analyze security vulnerabilities"
gemini -p "Review code quality metrics"
```

**Low-Risk Changes**
```bash
# Documentation and comments
droid exec "Add docstrings to all functions" --auto low
codex exec --full-auto "Update README with installation instructions"
```

**Development Operations**
```bash
# Package installation, test running
droid exec "Install dependencies and run tests" --auto medium
codex exec --full-auto "Fix failing unit tests"
```

**High-Risk Changes (Use Carefully)**
```bash
# Production deployments, major refactoring
droid exec "Implement OAuth2 migration" --auto high
# Only in isolated environments
codex exec --yolo "Complete system refactoring"
```

### 3. Input/Output Patterns

**Piping Content**
```bash
# Analyze git diff
git diff | claude -p "Review these changes for bugs"

# Process error logs
cat error.log | qwen -p "Categorize and summarize these errors"

# Multiple files
find . -name "*.py" | xargs claude -p "Check for anti-patterns"
```

**File-based Prompts**
```bash
# Read from prompt file
droid exec -f migration_prompt.md

# JSON output for parsing
gemini -p "List all API endpoints" --output-format json
```

**Structured Output**
```bash
# Machine-readable output
opencode -p "Count lines of code" -f json
claude -p "Generate test coverage report" > coverage_report.md
```

Important to know for Claude Code!
When you use `Bash` tool, you have to specify the timeout at least 15 min when you attempt to run any of these headless cli agents

## Common Workflows

### Code Review Automation
```bash
# Quick security scan
find . -name "*.py" | xargs claude -p "Check for security vulnerabilities"

# Performance analysis
git diff | codex exec --full-auto "Analyze performance impact of changes"

# Documentation consistency
droid exec "Verify all functions have docstrings" --auto low
```

### Test Generation
```bash
# Unit tests for specific module
claude -p "Generate comprehensive unit tests for auth.py using pytest"

# Integration tests
codex exec --full-auto "Create API integration tests with realistic data"

# Test coverage analysis
qwen -p "Analyze test coverage and suggest missing test cases"
```

### Documentation Automation
```bash
# API documentation
find src/ -name "*.py" | gemini -p "Generate OpenAPI specification"

# README generation
claude -p "Create comprehensive README with setup, usage, and examples"

# Changelog from commits
git log --oneline | qwen -p "Generate changelog from commit history"
```

## Integration Patterns

### CI/CD Integration

**GitHub Actions**
```yaml
- name: AI Code Review
  run: |
    git diff origin/main...HEAD | claude -p "Review for security and performance issues"
```

**GitLab CI**
```yaml
script:
  - gemini -p "Generate test suite for new features" --output-format json > test_plan.json
```

### Pre-commit Hooks
```bash
#!/bin/sh
# .git/hooks/pre-commit
git diff --cached | claude -p "Check staged changes for obvious bugs"
if [ $? -ne 0 ]; then exit 1; fi
```

### Monitoring and Alerts
```bash
# Daily code quality report
claude -p "Generate daily code quality report" | mail -s "Code Quality" [email protected]
```

## Troubleshooting

### Common Issues

**Agent not found**: Ensure CLI tools are installed and in PATH
```bash
which claude codex gemini opencode qwen droid
```

**Authentication errors**: Verify API keys and tokens
```bash
claude auth status
codex auth verify
```

**Permission denied**: Check file permissions and working directory
```bash
ls -la
pwd
```

**Context limit exceeded**: Reduce analysis scope or use specific files
```bash
# Instead of entire codebase
claude -p "Analyze main.py only"

# Or use specific patterns
find src/ -name "*.py" -maxdepth 2 | claude -p "Review these files"
```

### Debug Mode
Most agents support verbose output:
```bash
claude --verbose -p "Debug prompt"
codex exec --debug "Debug task"
```

## Resources

### references/

**agent-specific-commands.md** - Detailed command documentation for all six CLI agents including flags, options, and specific usage patterns. Load this when you need comprehensive syntax reference for a particular agent.