AI Builder - Headless AI Agents

This skill provides instructions for running popular AI code agents in headless (non-interactive) mode, enabling automation, scripting, and programmatic execution without user interaction.

When to Use This Skill

• Running AI code agents in automated pipelines or scripts
• Integrating AI agents into CI/CD workflows
• Executing batch tasks with AI agents programmatically
• Building web services or APIs that invoke AI agents
• Running AI agents without terminal interaction

Your Roles in This Skill

• DevOps Engineer: Configure and execute headless agent commands, set up automation pipelines, and handle environment configuration.
• Backend Developer: Integrate headless agents into applications, scripts, or services.

Role Communication

As an expert in your assigned roles, you must announce your actions before performing them using the following format:

As a {Role} [and {Role}, ...], I will {action description}

This communication pattern ensures transparency and allows for human-in-the-loop oversight at key decision points.

Instructions

Follow these steps to run an AI code agent in headless mode:

Step 1: Identify the AI Code Agent

Determine which AI code agent to run in headless mode. Route to the appropriate reference file:

• If using Claude Code, refer to references/claude-code.md
• If using Codex, refer to references/codex.md
• If using Gemini CLI, refer to references/gemini-cli.md
• If using other AI code agents, run <agent-name> --help to discover available flags for non-interactive/headless mode. Look for flags like --print, --non-interactive, --batch, --yes, --auto-approve, or similar

Step 2: Verify Installation

As a DevOps Engineer, verify the agent is installed:

# Claude Code
claude --version

# Codex
codex --version

# Gemini CLI
gemini --version

If not installed, use the dev-swarm-install-ai-code-agent skill.

Step 3: Choose Execution Mode

Each agent supports different headless modes:

Agent	Mode	Use Case
Claude Code	--print	Print output and exit (piping)
Codex	exec	Non-interactive execution
Gemini CLI	Positional prompt	One-shot execution

Step 4: Configure Permissions

Important: Headless mode typically requires bypassing permission prompts.

Agent	Permission Flag	Security Note
Claude Code	--dangerously-skip-permissions	Bypasses all prompts
Codex	--ask-for-approval never	Auto-approve all actions
Gemini CLI	--yolo	Auto-accept all actions

Security Warning: Only use these flags in trusted, sandboxed environments.

Step 5: Execute the Agent

Refer to the agent-specific reference file for detailed command syntax and examples.

Quick Reference (Minimal Commands):

# Claude Code (headless)
claude --print --dangerously-skip-permissions "your prompt here"

# Codex (headless)
codex --ask-for-approval never --sandbox workspace-write exec "your prompt here"

# Gemini CLI (headless)
gemini --yolo --sandbox "your prompt here"

Step 6: Handle Output

Configure output format based on your needs:

• Text output: Default for all agents
• JSON output: Available for structured processing
• Streaming output: For real-time processing

See agent-specific reference files for output format options.

Key Principles

• Security first: Only use permission-bypass flags in sandboxed/trusted environments
• Sandbox when possible: Use sandbox modes to limit agent capabilities
• Structured output: Use JSON output for programmatic processing
• Timeout handling: Set appropriate timeouts for long-running tasks
• Error handling: Check exit codes and stderr for failures

Common Issues

Issue: Agent hangs waiting for input

• Solution: Ensure all permission-bypass flags are set correctly

Issue: Command not found

• Solution: Verify agent is installed and in PATH

Issue: Permission denied errors

• Solution: Check working directory permissions and sandbox settings

Issue: Output parsing fails

• Solution: Use JSON output format (--output-format json) for reliable parsing