hekma
Menu

docs · adapters

Codex#

Unreleased: after 0.11.0. This page is on Hekma's main branch and ships in the next release; Hekma 0.11.0 does not have it.

OpenAI's Codex CLI has no native ACP mode; it integrates through a third-party codex-acp adapter binary that speaks the protocol on its behalf. Hekma ships no such adapter — treat the adapter as its own supply-chain decision.

Register#

The adapter binary below is the third-party wrapper, not Codex itself and not anything Hekma distributes:

hekma agent config set my-codex acp.command "codex-acp"
hekma agent register my-codex --kind acp
hekma agent start my-codex

Pass whatever additional arguments your chosen adapter documents via acp.args.

Honesty table#

The pause and interaction levels are the acp kind's own capability declaration — identical for every ACP agent and proven by the conformance kit against a scripted stand-in; they are not per-agent promises. The metering rows are characterized, not run-verified here.

SurfaceValueEvidence class
pauseguaranteed (Linux), guaranteed (macOS), best-effort (Windows)contract-validated
interactionguaranteed (all OSes)contract-validated
Metering sourceself-reportedcontract-validated
Billing-grade tokens— — no billing-grade usage in the ledger — tiers attempted: observed: not-configured; sentinel: no-lines-seen; no context usage reported (ACP usage_update is context-grain, never billed). No sentinel emission is documented upstream; the engine-observed tier is plausible (Codex's model_providers take base URLs) — a hypothesis, unproven herecharacterized
Context usagean agent-reported usage_update would surface under acp_context_usage — context-grain, never billed; whether the adapter reports one is unverified herecharacterized

Validation status. Upstream: third-party adapter (the ACP surface is an independently maintained wrapper, outside OpenAI's own release cycle and outside Hekma's). Evidence: characterized — upstream documentation, dated 2026-10-23, NOT run-verified here. Nothing pinned.

PATH requirement#

The launch command is the bare word codex-acp, resolved through the PATH of the environment hekma runs in. Hekma does not bundle, install or pin the adapter (or Codex) — install whichever adapter you choose, vet it yourself, keep it on the PATH. A start whose codex-acp cannot resolve fails with the engine's launch-failure diagnostic naming the executable.

Re-validation duty#

A third-party adapter can drift independently of both Codex and Hekma; every characterization here is a snapshot by design. Re-validate your adapter + Codex combination before relying on agent-specific behaviour — Re-validation states the full duty, including the contract duties that no automated kit can prove.