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 CI/CD pipelines, shell scripts, and other 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

Use this skill when:

• CI/CD Pipelines: Automated code reviews, test generation, documentation
• Shell Scripts: Repetitive coding tasks, bulk operations
• Cron Jobs: Scheduled maintenance, analysis tasks
• Git Hooks: Pre-commit validation, post-commit analysis
• DevOps Automation: Infrastructure as code, deployment preparation

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

# 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

# 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

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

Read-Only Mode (Safest)

# Analysis without changes
droid exec "Analyze security vulnerabilities"
gemini -p "Review code quality metrics"

Low-Risk Changes

# Documentation and comments
droid exec "Add docstrings to all functions" --auto low
codex exec --full-auto "Update README with installation instructions"

Development Operations

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

# 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

# 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

# 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

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

Common Workflows

Code Review Automation

# 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

# 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

# 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

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

GitLab CI

script:
  - gemini -p "Generate test suite for new features" --output-format json > test_plan.json

Pre-commit Hooks

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

# Daily code quality report
claude -p "Generate daily code quality report" | mail -s "Code Quality" team@example.com

Best Practices

Security

• Never use --yolo or equivalent flags in production environments
• Validate AI-generated code before deployment
• Use read-only mode for security-sensitive analysis
• Implement human review for high-risk changes

Performance

• Limit the scope of analysis (specific files vs entire codebase)
• Use structured output formats for programmatic processing
• Cache results when appropriate
• Monitor API usage and costs

Reliability

• Include fallback mechanisms for AI agent failures
• Validate generated code with linters and tests
• Use specific, well-defined prompts for consistent results
• Implement retry logic for network issues

Error Handling

# Robust script pattern
if ! claude -p "Generate tests" > tests.py; then
  echo "AI generation failed, using fallback"
  cp fallback_tests.py tests.py
fi

Troubleshooting

Common Issues

Agent not found: Ensure CLI tools are installed and in PATH

which claude codex gemini opencode qwen droid

Authentication errors: Verify API keys and tokens

claude auth status
codex auth verify

Permission denied: Check file permissions and working directory

ls -la
pwd

Context limit exceeded: Reduce analysis scope or use specific files

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

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.

use-case-examples.md - Practical examples for CI/CD pipelines, shell scripts, and automation workflows. Load this when implementing specific automation scenarios or need concrete implementation patterns.

scripts/

validate-agent-setup.py - Optional helper script to verify agent installations, API authentication, and basic functionality. Execute this to check if the required CLI agents are properly configured before using them in automation.

---

References contain detailed command documentation and practical examples that complement this guide.