Engines: Choosing the Agent's Brain

By the end of this chapter you can select and configure the engine — the coding agent that interprets your Markdown — and understand the portability that gh-aw's engine-neutral design buys you. You'll know the four production engines, the one field that switches between them, and how to pin a version for reproducible, secure builds.

Everything targets gh aw v0.81.6. We take the same Repo Assistant and swap its brain from Copilot to Claude — changing exactly one block of frontmatter.

A workflow has two separable parts: what you want done (the Markdown intent and the safe-outputs boundary) and who does the thinking (the model behind the agent). gh-aw keeps these apart on purpose. The engine is a pluggable component; the workflow around it — triggers, permissions, safe outputs, the compiled hardening — stays the same no matter which model you choose.

Why decouple the brain?

Tying automation to one vendor's model is a bet you might regret. Prices change, a competitor ships a better model, your org standardizes on a provider you already pay for, or a model you depend on is deprecated. If your workflow's logic were entangled with a specific model's API, every one of those events would be a rewrite. gh-aw's answer is blunt and reassuring: “You can switch later by changing only engine: and the corresponding secret” (AI Engines).

This is the same “prose is the source” idea from Chapter 3, viewed from the other side. Because your intent lives in portable natural language rather than model-specific API calls, the intent survives a change of engine. The engine is a runtime detail, not the architecture.

The engine: frontmatter field “specifies which AI engine interprets the markdown section” (Frontmatter). At its simplest it's one word:

engine: copilot   # the default — this line can be omitted entirely

The four production engines

Each engine is a real coding-agent CLI, and each needs its own credential — configured as a GitHub Actions secret, never in the workflow (AI Engines):

“Copilot CLI is the default — engine: can be omitted when using Copilot” (AI Engines). (There are also experimental engines — crush, opencode, pi — but the four above are the ones to build on.)

The object form: version, model, and more

When you need more than the default, engine: becomes an object. The two fields you'll use most are version (which CLI release to install) and model (which model to run):

engine:
  id: claude
  version: "2.1.70"          # pin the CLI release for reproducible builds
  model: claude-sonnet-4.5   # override the engine's default model

Pin your version. By default gh-aw installs the latest engine CLI, and the compiler will warn you about it: an unpinned latest is “a supply chain security risk… can change unexpectedly.” Pinning gives you “reproducible builds” and shields you from a surprise CLI release (AI Engines). This is the same hardening instinct as SHA-pinning actions in Chapter 3.

Because switching is cheap, this is a low-stakes decision — but the official guidance gives clear starting points. “Choose the engine that best matches your needs and existing AI account” (AI Engines):

Not every feature is available on every engine. A few notable differences from the engine comparison (AI Engines): max-turns (an iteration cap for long reasoning) is a Claude feature; max-continuations (autopilot) and custom agent files (engine.agent) are Copilot-only. The top-level max-turns (default 500) and max-ai-credits (default 1000) budgets, however, work across all engines.

When not to fiddle with engines

• Don't override the default without a reason. Copilot is the default because it has the widest feature coverage and the simplest billing. Start there; switch only when a concrete need (a model you prefer, a budget you already hold) appears.
• Don't ship version: latest to production. It's convenient for experimentation but it's an unpinned dependency — the compiler warns you for good reason. Pin before you rely on it.
• Don't put keys in the workflow. Every engine reads its credential from a GitHub Actions secret. A key in frontmatter is a leak; in strict mode it's a compile error.
• Don't chase models for their own sake. The engine rarely decides whether a workflow succeeds — clear instructions and the right tools matter far more. Change the brain last, not first.

Let's prove the portability claim. We take the Repo Assistant's triage instructions — the exact prose from Chapter 2 — and run them on Claude instead of Copilot. Only the engine: block changes.

on:
  issues:
    types: [opened]
  workflow_dispatch:
engine:
  id: claude
  version: "2.1.70"
  model: claude-sonnet-4.5
permissions:
  contents: read
  issues: read
network: defaults
safe-outputs:
  add-comment:
    max: 1
  add-labels:
    allowed: [bug, enhancement, question, documentation]
    max: 1

Set the Copilot version side by side and the diff is a single block: engine: copilot becomes the three-line Claude object. The triggers, the read-only permissions, the network posture, and the entire safe-outputs: boundary are untouched — and so is the Markdown body. That is engine-neutrality made concrete.

Compiling reveals gh-aw's two engine-related guardrails at work. First, if you leave version: latest, the compiler warns that an unpinned CLI is a supply-chain risk — so we pinned 2.1.70. Second, switching to Claude introduces a new secret, and the compiler's safe-update mode asks you to review it:

gh aw compile examples/ch05/repo-assistant-claude.md
# New restricted secret(s):
#   - ANTHROPIC_API_KEY
# Remediation: use --approve once you've confirmed the change is intentional.

gh aw compile --approve examples/ch05/repo-assistant-claude.md
# ✓ examples\ch05\repo-assistant-claude.md (105.0 KB)
# ✓ Compiled 1 workflow(s): 0 error(s), 0 warning(s)

You can now choose and configure the agent's brain with confidence:

• gh-aw is engine-neutral by design: your intent and safe-outputs boundary are portable, and you “switch later by changing only engine: and the corresponding secret.”
• Four production engines — Copilot (default), Claude, Codex, Gemini — each read a credential from a GitHub Actions secret, never the file.
• The object form adds version and model; pin the version for reproducible, supply-chain-safe builds.
• Pick by feature and existing budget (Copilot = broadest features; Claude = max-turns control; Codex/Gemini = models you already use) — and change the engine last, since instructions and tools matter more.
• Changing engines trips a secret-review gate — a first taste of the security model to come.

What's next. That's Part I complete: you can author, compile, trigger, and power a workflow. But so far the Repo Assistant only ever proposed writes through safe-outputs: without our examining how. In Chapter 6: Safe Outputs — the opening of Part II — we finally open that boundary and see how an agent acts on your repo without ever holding raw write access.