X-School-Academy 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> --helpto 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