Skip to main content
@obversa/engine-codex-cli runs Codex as an engine: every request is one fresh codex process. Use it to put an OpenAI model in a writing, verification or review seat, and in particular as the reviewer of a Claude seat, since a workflow() needs the two from different families.

​
Install

Included in @obversa/obversa.

​
Requirements

  • The Codex CLI installed and signed in. The codex command must be on your PATH, or you pass its path as cliBinary.

​
Identity

The plugin reports provider: 'openai' and model family gpt. It runs the model the request names, or defaultModel when the request names none; with neither set, the CLI runs without a model flag.

​
Quickstart

codex(model) is the seat helper a workflow() role takes:
examples/teams/writer-reviewer-pair.ts (excerpt)
The seat runs Codex sandboxed to the workspace with approvals off. Pass CodexSeatOptions (sandbox, approvalPolicy) to choose otherwise. new CodexEngine(options) is the same engine without the seat identity. The prompt goes through standard input, and the final message is read from a temporary file.

​
Options

​
sandbox

Without a workspace mode or a sandbox option, Codex runs in its read-only sandbox. The write workspace mode or sandbox: 'workspace-write' lets it write. permissionMode: 'bypassPermissions' turns the sandbox off.

​
clean

true runs Codex with --ignore-user-config. Your own config.toml stays out, with your settings, MCP servers and plugins, and so does the AGENTS.md in your Codex home folder. The repository’s instruction files still apply, and the run keeps your login. With your own settings out, Codex runs its own default model unless the seat or request names one. CodexSeatOptions takes the same clean option. Its row in the engines table: runs on your setup, clean mode available, read-only held in both modes. Your own skills and command rules still load in clean mode: Codex has no switch that leaves out your skills, and its switch for rules also leaves out the repository’s.

​
The rest

​
Errors

  • EngineError of kind missing-cli when the executable can’t run.

​
API

  • codex(model, options?): a TeamSeat for a workflow role. Quickstart.
  • CodexEngine: the engine class. CodexEngineOptions, CodexSeat, CodexSeatOptions: its types.
  • buildCodexArgs: the argument builder, exported for tests.

​
Next steps