## Definition
A **headless agent in CI** is an agentic CLI invocation in non-interactive mode, typically gating pull requests by reviewing the diff against the spec. In Claude Code: `claude -p <prompt> --output-format json --max-turns N`.
## Canonical GitHub Actions Workflow
```yaml
name: Agentic review
on:
pull_request:
types: [opened, synchronize]
jobs:
review:
runs-on: ubuntu-latest
permissions:
pull-requests: write
contents: read
steps:
- uses: actions/checkout@v4
with: { fetch-depth: 0 }
- run: npm install -g @anthropic-ai/claude-code
- env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: |
claude -p "@.claude/agents/critic.md
The diff is git diff origin/${{ github.base_ref }}...HEAD.
The spec is openspec/changes/<slug>/proposal.md.
End with PASS or NEEDS_REVISION." \
--max-turns 6 \
--output-format text > review.md
- uses: peter-evans/create-or-update-comment@v4
with:
issue-number: ${{ github.event.pull_request.number }}
body-file: review.md
- run: |
if grep -q "NEEDS_REVISION" review.md; then
echo "::error::Agentic reviewer requested revisions"
exit 1
fi
```
## What It Buys
- Every PR gets a structured review against its own spec, posted as a comment.
- The reviewer can block merges automatically.
- Humans review the *review* first, not raw code.
## Cost Controls
1. **Sonnet over Opus** for routine reviews; Opus only for `critical:` labelled PRs.
2. **Cap `--max-turns`.** 6–10 usually right; more usually means thrashing.
3. **[[Prompt Caching]] the stable prefix** (spec + `AGENTS.md`) — dramatic per-PR savings on repeat runs.
## Bypass Procedure
Always document one — a label, a comment, an admin override. Gates without a bypass produce shadow workflows you don't want.
## Related
- [[Builder-Critic Pattern]]
- [[Verifier Independence]]
- [[Prompt Caching]]
- [[DORA Metrics]]