title: "Headless and CI/CD" last_updated: 2026-03-21 status: experimental difficulty: advanced prerequisites: [04-hooks-and-commands, 05-sub-agents]

Headless and CI/CD

Coming in V2. This module is scaffolded with an outline.

Core Question

How do agents run without me?

Module Outline

Concepts

  1. Headless mode — Running AI agents without an interactive terminal. The agent receives instructions programmatically and returns results via structured output (JSON).

  2. Why headless matters — Enables automation: agents can run in CI/CD pipelines, cron jobs, PR review bots, and other automated workflows.

  3. The trust boundary — Interactive sessions have a human in the loop. Headless mode does not. This changes the risk profile and requires stronger guardrails.

  4. CI/CD integration patterns:

    • PR review agent: automatically reviews code on pull request
    • Test generation: agent writes tests for changed code
    • Documentation updates: agent updates docs when code changes
    • Migration assistance: agent helps with version upgrades

  5. Guardrails for automated agents — Permission restrictions, output validation, cost limits, timeout controls, sandbox execution.

  6. Structured output — Using JSON output mode for machine-readable results that can be consumed by other tools in your pipeline.

  7. Monitoring automated agents — Logging, cost tracking, success/failure metrics, alerting on unexpected behavior.

Tool-Specific Content

  • Claude Code: --print flag, -p for headless, JSON output, GitHub Actions integration, SDK usage
  • Codex CLI: Non-interactive mode, automation patterns, scripting

Exercises

  1. Run your first headless command and parse the JSON output
  2. Create a GitHub Action that uses an AI agent to review PRs
  3. Build a cron job that generates a daily code quality report
  4. Set up cost monitoring and alerting for automated agent runs