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

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

# 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

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

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

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

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

# 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

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.