Run an AI coding agent headless in CI (exit codes and JSON)
codeaf do "<brief>" --json runs one job with nobody watching and prints one JSON object. Exit codes, budgets and a CI example for GitHub Actions.
CodeAF, the open-source (Apache 2.0) coding agent by AgentField, runs headless in CI with codeaf do "<brief>" --json: one brief in, one JSON object out with ok, stop, answer, files and spend_usd, and an exit code your pipeline can branch on (headless mode). Nothing in it stops to ask, so the deciding question for CI is not approvals but limits: time, money and what your job does with the result.
At a glance
| CodeAF headless | |
|---|---|
| Command | codeaf do "<brief>" --json |
| Output | One JSON object on stdout: ok, stop, answer, files, spend_usd; everything else on stderr |
| Exit codes | 0 done, 1 could not run, 2 did not finish, 3 a limit you set stopped it, 124 hit --timeout |
| Other verbs | codeaf exec (one worker, one pass), codeaf run (a saved program), codeaf senior-dev --json |
| Approvals | None to answer; no --yolo flag, because nothing stops to ask |
| Spend | Every call priced first; a plan that would cross the daily limit stops unless --yes-spend |
| Crew for one run | --cheap, --best, --pin worker=<model>, --slots <n> |
| Where it edits | The folder, in place |
The contract
codeaf do "Make the failing tests pass by fixing the code, not the tests." --jsondo is not the chat with the window hidden. The brief goes straight to a planner, a worker and a checker, and the worker's prompt has no ask tool, no approval cards and no history. In the docs' run of the same small fix, the chat's first call sent about 14,700 prompt tokens with 26 tools; do sent about 6,200 with 8 (headless).
All three verbs edit the folder in place, print the answer on stdout and everything else on stderr, and exit the same way: 0 done, 1 could not run, 2 did not finish, 3 a limit you set stopped it. A do that hits --timeout exits 124. The commands reference also lists 4, when it needed an answer from you, so treat any code but 0 as not done.
Pick the verb by what you need checked
doplans, may split the job, and has a checker judge the result. Use it when a checked answer matters.execruns one worker for one pass, with no plan and no checker. Use it for summaries and triage.codeaf senior-dev --max-cost 2 --json "<brief>"hands one large change to senior-dev, which works on its own branch and streams one JSON record per line. Its flags go before the brief;--verify-buildand--verify-testset the checks when they cannot be discovered (senior-dev).
Leaner calls are not always a smaller bill. On the docs' tiny fix, do cost $0.012 pinned to the chat's model against $0.0045 in the chat, because the checker reads the work again; exec cost $0.0032.
Limits in CI
On a fresh runner the defaults apply: a $500 daily limit as a backstop and $5 per task (budgets). Once today's spend reaches the daily limit, codeaf do starts nothing and says why. Use --timeout for wall-clock time, --cheap for a cheaper crew, and --slots to cap parallel workers. Give the runner a model key as a secret; for OpenRouter, CodeAF reads OPENROUTER_API_KEY (troubleshooting).
A GitHub Actions example
Example, not tested. It follows the docs' "CI job that fixes a red build" idea: run do with a timeout and open a pull request only if it exits 0.
name: fix-red-build
on: workflow_dispatch
jobs:
fix:
runs-on: ubuntu-latest
permissions:
contents: write
pull-requests: write
steps:
- uses: actions/checkout@v4
- name: Install CodeAF
run: |
curl -fsSL https://agentfield.ai/get/codeaf | bash
echo "$HOME/.codeaf/bin" >> "$GITHUB_PATH"
- name: Ask CodeAF to fix the build
id: agent
env:
OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
run: |
set +e
codeaf do "make the test suite pass" --json --timeout 20m > result.json
echo "code=$?" >> "$GITHUB_OUTPUT"
- name: Open a pull request only on exit 0
if: steps.agent.outputs.code == '0'
uses: peter-evans/create-pull-request@v7
with:
branch: codeaf/fix-red-build
title: "Fix the red build (CodeAF)"
body-path: result.jsonThe install puts the binary in ~/.codeaf/bin (README). Keep the pull request as the gate: CodeAF edits the runner's checkout, and a person or your existing checks decide what merges. To pin a release, use curl -fsSL https://agentfield.ai/get/codeaf | VERSION=<tag> bash.
Reviews and audits from a script
codeaf review run owner/repo#123 reads a GitHub pull request and saves a report; codeaf sec run --changes --base main audits changed code. They do not use the do --json contract and run no tests, so inspect their coverage and endings; posting a review is a separate explicit action (headless). See a pull-request review agent and an agent that fixes GitHub issues. For work that should run for hours, see a long-running coding agent.
When something else fits better
Claude Code runs non-interactively with claude -p; --output-format json returns the result with total_cost_usd, --allowedTools pre-approves tools, and Anthropic documents GitHub Actions and GitLab CI/CD integrations (Claude Code headless). Choose it if your team is on Claude and wants a maintained Action. Codex runs from scripts with codex exec; --json streams JSON Lines, --output-schema shapes the final answer, and codex exec runs in a read-only sandbox by default until you pass --sandbox workspace-write. OpenAI recommends its Codex GitHub Action in CI (Codex non-interactive mode). Aider takes one instruction with --message and exits, with --yes to confirm every prompt (Aider scripting); choose it for small scripted edits.
Questions people ask
Which AI coding agent runs headless in CI?
CodeAF does, with codeaf do "<brief>" --json. It prints one JSON object with ok, stop, answer, files and spend_usd, and exits 0 when done, 2 when unfinished and 3 when a limit stopped it.
How does a CI job know whether the agent succeeded?
Read the exit code first: 0 is done, and anything else is not done. Then read .answer and .files from the JSON on stdout; progress goes to stderr.
Does headless mode need approvals or a --yolo flag?
No. codeaf do takes no --yolo because nothing in it stops to ask. It still refuses spend: a plan that would cross your daily limit stops unless you pass --yes-spend.
Can I cap how long and how much a CI run spends?
Yes for time: --timeout 20m ends the run with exit 124. For money, every task is held to $5 by default and the daily limit stops new work once reached; codeaf senior-dev also takes --max-cost.
Is there an official CodeAF GitHub Action?
No, none is documented. Install the binary with the install line in a workflow step, as in the untested example above.
Sources
- CodeAF docs: headless mode, commands, budgets, senior-dev, troubleshooting, checked 2026-11-21.
- CodeAF README (dev branch) for the install path and
VERSION=<tag>. - Claude Code headless, Codex non-interactive mode, Aider scripting, checked 2026-11-21.
Last updated 2026-11-21. Checked against CodeAF v0.8.3 docs and the Claude Code, Codex and Aider documentation on that date. The workflow above is an example and has not been run.