Last updated · Santosh Kumar Radha

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
Commandcodeaf do "<brief>" --json
OutputOne JSON object on stdout: ok, stop, answer, files, spend_usd; everything else on stderr
Exit codes0 done, 1 could not run, 2 did not finish, 3 a limit you set stopped it, 124 hit --timeout
Other verbscodeaf exec (one worker, one pass), codeaf run (a saved program), codeaf senior-dev --json
ApprovalsNone to answer; no --yolo flag, because nothing stops to ask
SpendEvery 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 editsThe folder, in place

The contract

bash
codeaf do "Make the failing tests pass by fixing the code, not the tests." --json

do 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

  • do plans, may split the job, and has a checker judge the result. Use it when a checked answer matters.
  • exec runs 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-build and --verify-test set 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.

yaml
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.json

The 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

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.