CodeAF: the default harness

CodeAF is the default coding harness for app.harness(...) in Python, Go, and TypeScript. Set OPENROUTER_API_KEY for the default OpenRouter model, then dispatch a task:

export OPENROUTER_API_KEY="your-key"
af codeaf ensure
af harness doctor --provider codeaf

from pydantic import BaseModel

class Review(BaseModel):
    summary: str
    files: list[str]

result = await app.harness(
    "Review the authentication code and summarize the findings.",
    schema=Review,
    cwd="/path/to/repo",
    max_turns=20,
)

The equivalent SDK calls are agent.harness(task, { schema, maxTurns: 20 }) in TypeScript and agent.Harness(ctx, task, schema, &dest, harness.Options{MaxTurns: 20}) in Go. See Harness orchestration for complete examples.

CodeAF enforces turn and time limits only. The SDK does not translate max_budget_usd, tools, or permission_mode into CodeAF controls. Those options do not impose a dollar cap, tool allowlist, or permission policy on the default worker. The legacy aforge adapter did not enforce them either.

Upgrading to v0.1.143

Calls with no provider and unpinned provider="aforge" now run CodeAF. Results and usage are attributed to codeaf, including calls through the alias. Existing tasks may use a different model and execution protocol. The first call can download about 70 MB, and provisioning counts against the harness timeout.

To roll back, set AFORGE_BIN to an existing legacy aforge executable in the agent process environment:

export AFORGE_BIN="/absolute/path/to/aforge"
# If you need the legacy binary first:
af aforge ensure

The pin selects the legacy adapter for an implicit default or provider="aforge". Python HarnessConfig.aforge_bin, TypeScript aforgeBin, and Go Options.BinPath are SDK legacy pins too. Go's shared BinPath is treated as a legacy pin with the implicit default; select Provider: "codeaf" to use it as a CodeAF override. Explicit provider="codeaf" takes precedence over legacy pins. Unset the pin to return to the new default.

Provisioning and restricted networks

The shell installer, successful af install, catalog skill installation, and Desktop launch ensure CodeAF best-effort. af run does not provision it. SDK-only installations can download it on the first harness execution; Python extras install wrappers, not CodeAF itself.

Binary resolution follows this order:

1. Explicit SDK CodeAF binary option: Python codeaf_bin, TypeScript codeafBin, or Go Options.BinPath with Provider: "codeaf".
2. CODEAF_BIN.
3. $AGENTFIELD_HOME/bin/codeaf with a matching .codeaf.version marker (~/.agentfield is the default home; Windows uses codeaf.exe).
4. A pinned, SHA-256-verified download of CodeAF v0.8.2 from GitHub, about 70 MB.
5. codeaf on PATH.
6. Managed or PATH legacy aforge, with a warning. Results identify the adapter that actually ran.

Pre-install before latency-sensitive work:

af codeaf ensure
af codeaf ensure --force          # download again to repair an installation
af codeaf ensure --lock-wait 30s  # bound waiting for another installer

Allow HTTPS egress to github.com and the release-asset hosts it redirects to. A bare PATH installation is checked after the managed download attempt. For a restricted network, place a trusted binary in the image or host and persist both settings in the agent's runtime environment:

export CODEAF_BIN="/opt/codeaf/codeaf"
export AGENTFIELD_SKIP_CODEAF=1

CODEAF_BIN bypasses managed downloading. The skip variable disables all CodeAF downloads, including explicit ensure, while still allowing an existing binary. Alternatively, run ensure on a connected build host and preserve the managed binary and its matching .codeaf.version marker. Model access still needs its own network connection and credentials.

AGENTFIELD_CODEAF_BASE_URL can point to a full mirror release directory, including the version. Embedded SHA-256 pins still apply. The CLI downloader honors HTTP_PROXY, HTTPS_PROXY, NO_PROXY, and lowercase equivalents. The TypeScript SDK skips its download when HTTPS_PROXY or https_proxy is set; pre-install with af codeaf ensure through the proxy or set CODEAF_BIN.

The shell installer accepts --no-codeaf (CODEAF_MODE=none); PowerShell accepts -NoCodeaf for a saved script. The shell opt-out applies to the installer and its child processes; it does not set skip variables in your calling shell. PowerShell skips its own CodeAF install. Persist AGENTFIELD_SKIP_CODEAF=1 separately in the agent's runtime environment to opt out of later SDK downloads. Legacy --no-aforge, -NoAforge, AFORGE_MODE=none, and AGENTFIELD_SKIP_AFORGE remain opt-out aliases.

For an SDK or Desktop setup on Windows, use the process environment:

$env:OPENROUTER_API_KEY = "your-key"
$env:CODEAF_BIN = "C:\tools\codeaf.exe"
$env:AGENTFIELD_SKIP_CODEAF = "1"
# For the piped PowerShell installer, set CODEAF_MODE before invoking it:
$env:CODEAF_MODE = "none"

The python-agent, go-agent, and control-plane-cloud Docker images ship /usr/local/bin/codeaf and set CODEAF_BIN to that path. Their builds fail if downloading or verification fails. The plain control-plane image does not bundle this worker. At runtime, supply the model key and a writable state directory; override CODEAF_BIN if you replace the image binary.

Execution and configuration

The SDK runs codeaf exec --json --dir <root> --model <model> with the task on stdin. project_dir (projectDir in TypeScript, ProjectDir in Go) takes precedence over cwd. max_turns becomes --max-turns; a system prompt becomes --system.

Setting	Behaviour
provider	Explicit per-call provider, then agent config, then AGENTFIELD_HARNESS_PROVIDER, then codeaf, subject to legacy pins above.
model	Explicit model, then CODEAF_MODEL, then legacy fallback AFORGE_MODEL, then ~deepseek/deepseek-v4-flash-latest. The SDK reads these values and strips one leading openrouter/. Per-call model environment overrides process values; blank means unset.
AGENTFIELD_CODEAF_COMMAND	exec by default. Blank/unset falls back to legacy AGENTFIELD_AFORGE_COMMAND; invalid commands warn and use exec.
AGENTFIELD_HARNESS_TIMEOUT_SECONDS	Outer timeout, default 1800 seconds, including provisioning and shared-download waits. The child receives remaining time with an inner timeout five seconds shorter, minimum one second.
CODEAF_MAX_CONCURRENT	Subprocess cap, default 8; legacy fallback AFORGE_MAX_CONCURRENT. Invalid or non-positive values use 8.
CODEAF_EXEC_REASONING	off, low, medium, or high; supported SDK variants map to this variable.

Set AGENTFIELD_CODEAF_COMMAND=do to opt into codeaf do --json --yes-spend. The SDK pins worker, plan, and check models, and sends the system prompt plus task on stdin. This route does not forward max_turns; CodeAF's own task spending limit still applies. AFORGE_EXEC_BUDGET is a legacy aforge setting, not a CodeAF budget control.

State and telemetry

SDK children default CODEAF_HOME to $AGENTFIELD_HOME/codeaf, isolated from ~/.codeaf, and CODEAF_NO_UPDATE_CHECK=1. They default CODEAF_TELEMETRY=off under truthy CI or DO_NOT_TRACK, or when AGENTFIELD_TELEMETRY_ENABLED is false (0, false, no, off). Explicit caller or per-call environment settings override these defaults. Inherited CODEAF_MODELS and AFORGE_MODELS are removed unless supplied in the per-call overlay.

Results and repair

A normal default result reports provider: "codeaf". done with ok=true succeeds; deadline is a timeout. An answer with unchecked, budget, or turn-cap is accepted as useful partial output, subject to schema validation. question, incomplete, error, and price stops fail. Inspect is_error, failure_type, cost_usd, and num_turns (camelCase in TypeScript).

af harness doctor --provider codeaf checks the binary and version without downloading or starting a model task. Its credential check reports presence only. If installation fails, check egress, writable managed storage, skip settings, and proxy configuration, then run af codeaf ensure or supply CODEAF_BIN.

Other providers include claude-code, codex, gemini, opencode, pi, and omp, plus grok in Python. See configuration and the CLI reference.