> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rippletide.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect OpenAI Codex

> Install local Codex hooks, choose what to record, and understand the limits of tool governance.

This path governs **Codex itself**, using its local hooks. It does not add SDK code to the repositories Codex edits. To use Codex to instrument another agent, follow [Connect an agent](https://docs.rippletide.com/docs/connect-agent.md) instead.

## Requirements and setup

Install Codex first. Rippletide's adapter requires Codex 0.154.0 or later; it has been verified with CLI versions 0.154.0 and 0.155.1. Recheck hook registration after upgrading Codex. Desktop builds must support and trust the same hooks; desktop behavior is not covered by the CLI verification alone.

On the machine that runs Codex:

```bash theme={"system"}
npm install -g rippletide-package
rippletide codex setup
```

The command signs in through the browser if needed and can create the Codex agent. A Workspace Admin must authorize CLI access. You can also choose **Connect → Codex** in the app and run its generated `rippletide codex setup --session <token>` command, or use `--agent <agentId>` for an existing agent.

Setup stores the Connection key in `~/.rippletide/codex.env`, merges the hooks into `~/.codex/hooks.json`, and registers their trust in `~/.codex/config.toml`. It backs up both Codex files and preserves other hooks. Codex silently skips untrusted hooks: if setup cannot register trust, follow its `/hooks` instructions before relying on enforcement.

## Choose what to store

Setup asks separately whether to:

* **Store activity:** tool calls and their outcomes become traces. The default is **No**, including in a non-interactive terminal. `--traces` or `--no-traces` selects explicitly. With traces off, decisions and receipts are still recorded, but the activity-based connection status may remain declared.
* **Import history:** only offered when storing activity. Default **No**. `--backfill` imports past sessions once; `--no-backfill` declines.

Recorded activity withholds input/output content by default. To include bounded tool inputs/results and final response content, set `RIPPLETIDE_CAPTURE_CONTENT=true` in `~/.rippletide/codex.env` after owner consent. Setup preserves this setting but does not enable it. Repository and shell `RIPPLETIDE_*` settings do not configure the adapter. See [Privacy & capture](https://docs.rippletide.com/docs/privacy.md). Run a new Codex session with a tool call to verify the live hooks and its decision receipt. A historical import does not prove that a live hook is installed.

## What the hooks can govern

| Surface | Coverage |
| - | - |
| Shell/unified exec, `apply_patch`, MCP tools, declared local function tools | Policy check before the call, when Codex routes it through the supported hook path |
| Completion of a tool call | Post-tool evidence and execution receipt |
| Hosted tools such as `WebSearch` | Not governed by local hooks |
| `write_stdin` into an open exec session | Not governed or recorded by the hook |
| The JavaScript body of an `exec` cell | No hook on the cell; covered nested tool calls are checked |
| Final response | Stop evaluates the last assistant message and can request a revision; delivery or suppression is not confirmed |
| Tool result filtering | Cannot be enforced after the effect through the post-tool hook |

Shell payloads expose the command but not every execution flag or working directory. Some subagent message bodies are encrypted by Codex and unavailable for matching. Unknown or changed tool payloads require compatibility verification. These hooks are a guardrail, not complete coverage of everything Codex can do.

An enforced `BLOCK` becomes a native deny before the covered call. Availability failures such as network outages, rate limits, 5xx and timeouts fail open. Deterministic policy rejections and arguments too large/deep to evaluate are refused. A missing, untrusted or crashed hook can leave a call ungoverned.

At Stop, Rippletide evaluates Codex's complete last assistant message against before-response Rules. An enforced `BLOCK` requests that Codex revise the response. Observe decisions allow stopping. Evaluation errors, invalid replies and timeouts fail open. The check sends `request: null`, so the original user request is unavailable for matching.

Stop review does not produce a delivery or suppression receipt and is separate from the required Codex connection-proof contract. It sends the complete response for policy evaluation and decision audit even when activity storage or content capture is off. See [Privacy & capture](https://docs.rippletide.com/docs/privacy.md).

Check `~/.rippletide/codex-hook.log` and recent decision receipts when diagnosing coverage. An authorized call with no post-tool evidence has an unknown outcome; authorization alone is not proof it executed.

## Import past sessions explicitly

```bash theme={"system"}
rippletide codex backfill --dry-run --stats
rippletide codex backfill --since 2026-09-01
```

Backfill reads Codex's own sessions under `~/.codex/sessions` and imports them as backdated evidence. Review the dry run first. Content is withheld by default. `--capture-content` explicitly includes bounded prompts, patches, commands and outputs for that import. The same opt-in can be configured with `RIPPLETIDE_CAPTURE_CONTENT=true` in `~/.rippletide/codex.env`. Re-runs skip already imported sessions using local state.

Historical turns are not re-evaluated against today's Rules and do not prove earlier enforcement. They can show **No policy check**. Keep historical evidence separate from proof that a live guard blocked an action.

## Maintain or remove

Run `rippletide codex catalog` to rebuild the declared tool catalogue. Re-run setup to repair registration or change the traces choice. To remove the integration:

```bash theme={"system"}
rippletide codex setup --uninstall
```

Review the uninstall summary for local cleanup. Previously stored server evidence is not erased by removing local hooks. `rippletide logout` separately revokes the CLI's Platform key.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.