# SageOx + Codex (/docs/developers/codex)



SageOx + Codex [#sageox--codex]

OpenAI Codex is a bundled, **Silver-tier** ox integration. `ox init` wires it up:
Codex primes your Team Context at session start, its hooks fire, and its sessions
are captured to the Ledger in real time — the same prime-work-capture loop every
agent gets, with a touch less depth than [Claude Code](/docs/developers/claude-code).

For the general model — how priming injects Team Context and how sessions are
captured — read [how it works](/docs/developers/how-it-works) first. This page
covers what's Codex-specific.

Setup [#setup]

<Terminal>
  <TerminalCommand>
    curl -sSL 

    [https://raw.githubusercontent.com/sageox/ox/main/scripts/install.sh](https://raw.githubusercontent.com/sageox/ox/main/scripts/install.sh)

     \| bash
  </TerminalCommand>

  <TerminalCommand>
    ox login
  </TerminalCommand>

  <TerminalCommand>
    cd ~/code/my-project
  </TerminalCommand>

  <TerminalCommand>
    ox init
  </TerminalCommand>
</Terminal>

`ox init` configures Codex to run `ox agent prime` at session start. Codex's
adapter ships inside ox — no separate install.

Enable hooks [#enable-hooks]

Codex hooks are opt-in. Turn them on once so session capture and lifecycle
events fire automatically:

<Terminal>
  <TerminalCommand>
    codex features enable codex_hooks
  </TerminalCommand>
</Terminal>

Verify the wiring:

<Terminal>
  <TerminalCommand>
    ox doctor
  </TerminalCommand>
</Terminal>

What's Codex-specific [#whats-codex-specific]

| Aspect            | Codex behavior                                                                                  |
| ----------------- | ----------------------------------------------------------------------------------------------- |
| Tier              | Silver — core parity with Claude Code's Gold                                                    |
| Source            | Bundled (ships inside ox)                                                                       |
| Session capture   | Real-time, tailing append-only JSONL session files                                              |
| Hooks             | `SessionStart`, `PreToolUse`, `PostToolUse`, `Stop` (after `codex features enable codex_hooks`) |
| Context injection | `ox agent prime` at session start                                                               |

The one deliberate step Claude Code doesn't need: enabling `codex_hooks`. After
that, capture and priming run without you thinking about them. See the
[support matrix](/docs/developers/coding-agents) for how the tiers compare.

Recipe 1: Context-aware Codex sessions [#recipe-1-context-aware-codex-sessions]

Start Codex as normal. ox primes your Team Context first, so Codex follows your
team's patterns instead of generic best practices from its training data — it
knows your conventions, architecture decisions, domain terms, and current work
before it writes a line.

Recipe 2: Feed recordings into Codex context [#recipe-2-feed-recordings-into-codex-context]

Import your Loom walkthroughs, Figma design sessions, and team recordings. Codex
references them during implementation — citing the designer's explanation from a
walkthrough, not just interpreting a static mockup.

Import via the [web UI](https://sageox.ai); recordings are transcribed and added
to Team Context, which flows to Codex via `ox agent prime`. See
[Video import](/docs/context-capture/video-import).

Recipe 3: Multi-agent workflows [#recipe-3-multi-agent-workflows]

Run Codex alongside other agents — they all share one Team Context. A decision
discovered in one session becomes available to every future session, regardless
of which agent surfaced it.

<Mermaid
  chart="graph TD
    TC[&#x22;Team Context&#x22;] --> C1[&#x22;Codex session&#x22;]
    TC --> C2[&#x22;Claude Code session&#x22;]
    TC --> C3[&#x22;Cursor session&#x22;]
    C1 -->|new insights| TC
    C2 -->|new insights| TC"
/>

Recipe 4: Codex in CI/CD pipelines [#recipe-4-codex-in-cicd-pipelines]

Running Codex in automated pipelines (code review, test generation, docs)?
Authenticate with a [Personal Access Token](/docs/cli/pats) instead of
`ox login`:

```bash
export SAGEOX_TOKEN="${{ secrets.SAGEOX_TOKEN }}"
ox agent prime
```

ox auto-detects the CI environment and skips the daemon, local Ledger, and
CodeDB setup — no flag required. See
[Running ox in constrained environments](/docs/cli/ephemeral-mode) for the full
reference, including Claude Code Cloud, Devin, and GitHub Actions recipes.

Best practices [#best-practices]

**Enable `codex_hooks` once per machine**
Without it, priming still works but session capture is manual. Turn it on so the
loop closes automatically.

**Record decisions that affect code patterns**
The more context in your Team Context, the better Codex performs. Record
architecture calls, design decisions, and convention changes.

**Review what Codex receives**
Browse `.sageox/teams/primary/` to see your Team Context. Edit `AGENTS.md` to add
conventions Codex should follow.

What's next [#whats-next]

* [How it works](/docs/developers/how-it-works) — the general prime-work-capture model
* [SageOx + Claude Code](/docs/developers/claude-code) — the deepest, Gold-tier integration
* [Supported coding agents](/docs/developers/coding-agents) — every agent and its tier
* [Team Context](/docs/features/team-context) — what's in the context Codex receives