Codex harness reference
CodexOpts (packages/core/src/harness.ts) configures the codex() harness factory for Codex SDK-backed turns. Pass it as codex(opts); every field is optional.
CodexOpts
| Option | Type | Default | When to set |
|---|---|---|---|
model | CodexModel | Codex SDK default | Pin a default model for all turns from this harness instance; per-turn run.model/opts.model wins. |
skipGitRepoCheck | boolean | false | Set to true when running in generated or temporary workspaces that are not Git repositories. |
Per-run options
These are set per runUnstructuredTurn/runStructuredTurn call via HarnessTurnOptions (the harness-agnostic options harnessCall accepts), not on CodexOpts:
| Option | Type | Notes |
|---|---|---|
cwd | string | Required; working directory passed to the Codex thread. |
access | 'read' | 'edit' | Defaults to 'read'; maps to Codex read-only or workspace-write sandbox mode. |
resume | string | Resumes a prior Codex thread by ID, used for same-session structured-output repair. |
model | HarnessModel | Per-turn override of CodexOpts.model. |
timeoutMs | number | Per-turn timeout. When omitted, the built-in Codex harness uses Orchard's default 30 minute harness timeout. |
onEvent | (event: unknown) => void | Accepted by the shared interface; the current Codex SDK harness does not emit raw stream events through this option. |
Example
import { DEFAULT_CODEX_MODEL, codex } from '@snevins/orchard-core/harness'
const harness = codex({
model: DEFAULT_CODEX_MODEL,
skipGitRepoCheck: true,
})Supported model catalog
SUPPORTED_CODEX_MODELS mirrors the model slugs returned by codex debug models for the current Orchard-maintained harness surface:
import { SUPPORTED_CODEX_MODELS } from '@snevins/orchard-core/harness'Current entries: gpt-5.5, gpt-5.4, gpt-5.4-mini, gpt-5.3-codex-spark, and codex-auto-review.
The CodexModel type includes those known values while still accepting custom strings so newly released or account-specific CLI models can pass through to the Codex SDK without an Orchard release.
Access and sandbox mode
harnessCall passes the selected access level into the harness. For Codex:
| Orchard access | Codex sandbox mode |
|---|---|
'read' | read-only |
'edit' | workspace-write |
Omitting access defaults to read-only unless the task receives an orchard.access header from helpers such as runReadOnlyParallelTasks.
Optional dependency
@openai/codex-sdk is an optional dependency. Orchard imports it only when codex() runs a turn. If the package cannot be loaded, codex() throws a NonRetryableHarnessError with an install hint such as:
codex: failed to load @openai/codex-sdkInstall the SDK in the host project before using codex():
pnpm add @openai/codex-sdkStructured output
codex() implements runStructuredTurn, so harnessCall first asks the Codex SDK for schema-constrained output. If you need to inspect the structured path, use harnessCallWithTurn: native accepted output records turn.structuredMode as 'native', while JSON extraction or repair records 'extracted'.
Failure classification
Codex auth and invalid-model-shaped SDK errors are rethrown as NonRetryableHarnessError with a codex: prefix so the runtime does not retry unrecoverable configuration failures. Other Codex SDK failures are wrapped with the same prefix and can be retried by the task's retry policy.