Skip to main content

OpenAI Codex / CLI Integration

Technical guide to governing tasks assisted by code models in the command line and in headless environments with RAPID OS v3.

1. What it is and how it fits with RAPID OS​

OpenAI Codex and its associated command-line tools enable automated code generation and transformation in automated environments or developer terminals.

Fit with RAPID OS: RAPID OS acts as the deterministic governance layer that defines which changes are authorized through a specification (Spec) and a contract (ExecutionContract). Codex acts as the external coding engine that produces the patches and runs commands.

2. Configuration in RAPID OS​

RAPID OS includes the built-in codex profile:

rapid harness show codex

Declared output:

  • context.consume: supported
  • repository.read: supported
  • workspace.current: supported
  • repository.write, shell.execute, tests.execute: unknown (declared as subject to the permissions of the local environment).

To override these capabilities and declare that your local environment authorizes running tests and modifying files, you can initialize a project profile at .rapid-os/harnesses/codex.json.

3. User Configuration in Codex​

  1. Configure your runtime environment with the corresponding variables and API keys according to the official OpenAI documentation.
  2. Make sure the tool has read and write permissions on the repository.
  3. Configure the local execution sandbox to allow the tool to run python -m unittest.

Main workflow: shortcuts​

The recommended way to work with Codex is with the Rapid OS shortcuts. The 9 shortcuts, the loop they follow, human approval, and common errors are in the shortcuts guide.

Install​

rapid init --shortcuts                                # when initializing the project
rapid shortcuts install --harness codex               # in an already initialized project

It generates .agents/skills/rapid-*/SKILL.md (the 9 shortcuts; Codex skills documentation). It is the same folder Antigravity uses: if you select both, it is written only once. After updating Rapid OS, run rapid shortcuts install again.

Invoke: Codex CLI and IDE extension​

The shortcuts are Codex skills. According to the official skills documentation: "In Codex CLI or the IDE extension, run /skills or type $ to mention a skill". That is why the form that works in every Codex variant is $:

$rapid-init Billing API for small businesses, in Python
$rapid-feature add CSV export to the monthly report
Codex variantHow to invoke a shortcutWhat / shows
Codex CLI (codex in a terminal)$rapid-<mode>, or pick it from /skillsOnly Codex's own commands (/model, /skills…). /rapid-* does not appear: type $.
Codex extension for VS Code$rapid-<mode> or /skills; in the extension they also appear when you type /Codex commands and, in the extension, the skills.

Both variants read the same folder (the project's .agents/skills/, and ~/.agents/skills/ if you installed with --global), so there is no need to install anything different for each one. If $ does not show the rapid-* skills:

  1. Open Codex from the project root (Codex looks for .agents/skills from the working directory up to the repository root).
  2. Check that they exist: rapid shortcuts list --harness codex.
  3. Check that rapid is on the PATH of that terminal (rapid --version): the skill asks Codex to run it.
  4. If you updated Rapid OS or installed them while Codex was open, restart the Codex session.

$rapid-approve does not approve: it shows the pending gates and the evidence, and gives you the command for your terminal. rapid approve requires an interactive terminal of your own and fails with RAPID1310 if an agent launches it. The AGENTS.md file generated by rapid init still provides the project context.

Advanced mode (v3 commands)​

The v3 commands (rapid spec, rapid run, rapid evidence, rapid eval…) remain available for CI, debugging, and auditing, and you do not need to use them by hand day to day either. Sections 4 to 8 keep the full manual flow.

4. Context Bundle and Spec Delivery​

RAPID OS compiles an optimized context package:

rapid context --manifest

Deliver to the tool:

  • The active specification (.rapid-os/specs/<spec-id>/spec.json).
  • The compiled context manifest (.rapid-os/context/manifest.json).
  • The execution contract instructions (.rapid-os/runs/<run-id>/contract.json).

5. Respecting the Execution Contract and External Tools​

The harness must adhere to:

  • The immutable task list (T001, T002, ...).
  • The files authorized in the scope (paths).
  • The gates declared in the policy.

Before starting external execution, capture the baseline log as an artifact (base.log), record the baseline evidence (according to evidence_baseline.json), and acknowledge gate.baseline:

python -m unittest discover -s tests -t . > base.log 2>&1
rapid evidence add --run <run-id> --input evidence_baseline.json
rapid run gate <run-id> gate.baseline acknowledged
rapid run status <run-id> active
rapid run task <run-id> T001 in_progress

6. Recording Results and Evidence​

Once Codex applies the changes and runs the tests in the external terminal (see the canonical definition of each piece of evidence in the Under the hood lab):

  1. Ingest evidence of the modified files (evidence_files.json):
rapid evidence add --run <run-id> --input evidence_files.json
  1. Ingest evidence of the test result with the attached log (evidence_tests.json):
rapid evidence add --run <run-id> --input evidence_tests.json
  1. Ingest workspace evidence (evidence_workspace.json) and final review evidence (evidence_review.json):
rapid evidence add --run <run-id> --input evidence_workspace.json
rapid evidence add --run <run-id> --input evidence_review.json
  1. Update the run state:
rapid run gate <run-id> gate.tests acknowledged
rapid run gate <run-id> gate.final-verification acknowledged
rapid run task <run-id> T001 done
rapid run status <run-id> finished

7. Deterministic Evaluation​

Evaluate the validity of the execution:

rapid eval run --run <run-id> --write --require-pass

Windows: sandbox and git​

Why it happens. On Windows, Codex runs commands inside a sandbox. In its default mode (elevated) the commands run with dedicated, lower-privileged sandbox users (Windows sandbox). git, for its part, refuses to read a folder whose owner is not the user running it (detected dubious ownership). That Codex page describes the sandbox but does not mention git: the relationship between the two is this one, observed in practice. Result: what the harness runs and what you run by hand in your terminal see the same folder with a different owner.

What Rapid OS already solves. All of Rapid OS's git commands go through a single gateway (rapid_os/orchestration/git.py) that adds -c safe.directory=<project root> and -c core.fsmonitor=false. It trusts only the project root, never *, and disables fsmonitor (which allows a foreign repository to run programs when it is read). That is why rapid setup finish, rapid start, and rapid finish work inside the sandbox without asking you for anything. safe.directory on the command line is honored since git 2.38; in earlier versions git ignores it and Rapid OS treats it as untrusted (RAPID1416).

The only thing left for you. To use git yourself in that folder (git status, git commit...), your user's git needs the exception. Rapid OS detects it (it asks git the way you would, without those -c flags) and delivers it as an action in person_actions of rapid setup finish, rapid setup next --json (kind: done), and rapid doctor, and the shortcut shows it to you with its explanation:

git config --global --add safe.directory C:/path/to/your/project

The path is the project root written with /. It does not need administrator permissions (only your user reads it) and --system or * are never used. Run it in your own terminal: the agent must not do it for you.

Alternative: unelevated. If you prefer the commands to run with your own user, Codex allows the unelevated sandbox in config.toml:

[windows]
sandbox = "unelevated"

It has an isolation cost: according to the same page it is a legacy mode (legacy fallback) that uses a restricted token derived from your user instead of the sandbox-user boundary of elevated, with weaker network isolation (environment-level controls instead of the dedicated firewall rule) and no support for denied read paths. Rapid OS works the same with either one.

8. Common Problems​

  • The harness tries to modify paths outside the scope: The evaluation will detect discrepancies if the evidence does not match the contract's paths.
  • Missing test evidence: Do not try to close gate.tests without valid test_result evidence with exit_code: 0.