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

# Codex

> Integrate Entire with Codex for AI coding session capture

Codex is OpenAI's CLI coding agent. Entire integrates with Codex through Codex's native hook system, automatically capturing sessions and checkpoints. The Codex integration is in preview and may contain bugs.

## Prerequisites

* [Entire CLI installed](/cli/installation)
* [Codex installed and authenticated](https://help.openai.com/en/articles/11096431)
* A Git repository with Entire enabled

## Enable

```bash theme={null}
entire agent add codex
codex
```

`entire agent add codex` installs hooks into `.codex/hooks.json` and enables Codex's required `codex_hooks = true` feature flag in `.codex/config.toml` automatically — no manual config needed.

<AccordionGroup>
  <Accordion title="How it works">
    Entire integrates with Codex through project-level hook configuration in `.codex/hooks.json`. The hooks track the session lifecycle:

    1. **Session Start** — `SessionStart` creates a new Entire session.
    2. **Prompt Tracking** — `UserPromptSubmit` captures each user prompt.
    3. **Turn Completion** — `Stop` finalizes each turn and advances checkpoint state.
    4. **Transcript Capture** — Entire reads Codex's JSONL rollout transcript from `~/.codex/` or `CODEX_HOME`.
    5. **Session Storage** — data is saved to the `entire/checkpoints/v1` branch.
  </Accordion>

  <Accordion title="What gets captured">
    | Data         | Description                                        |
    | ------------ | -------------------------------------------------- |
    | Conversation | Full transcript of prompts and responses           |
    | File changes | Files modified via `apply_patch` in Codex rollouts |
    | Token usage  | Input, cached-input, output, and reasoning tokens  |
    | Timestamps   | Session, turn, and checkpoint timing               |
  </Accordion>

  <Accordion title="Features">
    **Rewind during sessions.** Use `entire checkpoint rewind` to restore to a previous checkpoint during or after a Codex session. When you rewind, Entire restores the checkpointed transcript state and shows the command to continue the Codex session. See the [`rewind` command reference](/cli/commands#rewind) for full flag documentation.

    **Resume previous sessions.** Switch to a session's branch with `entire session resume <branch>`. The CLI restores the session log if needed and prints `codex resume <session-id>`. See the [`resume` command reference](/cli/commands#resume) for full flag documentation.

    **Explain commits.** Inspect any commit or checkpoint with `entire checkpoint explain`. See the [`explain` command reference](/cli/commands#explain) for full flag documentation.
  </Accordion>

  <Accordion title="Caveats and limitations">
    1. **Subagent capture is not available.** Unlike Claude Code, Codex does not currently expose subagent lifecycle hooks, so Entire captures the main Codex session but not nested subagent sessions.
    2. **Session completion is turn-based.** Codex does not emit a distinct session-end hook. Entire relies on Codex's per-turn `Stop` hook and transcript data rather than a final shutdown event.
    3. **Transcript paths can be missing.** In ephemeral Codex runs, the transcript path may be null. Entire can still process hook events, but full transcript capture is limited in that mode.
    4. **`PreToolUse` is currently shell-only** and is not used for lifecycle tracking.
    5. **Transcript capture depends on Codex writing rollout JSONL files.**
  </Accordion>

  <Accordion title="Best practices">
    **Enable Codex through Entire.** Use `entire agent add codex` instead of manually editing `.codex/hooks.json`. Entire preserves existing Codex hook config and also writes the required `.codex/config.toml` feature flag.

    **Commit at logical points.** Create checkpoints at natural stopping points: after implementing a feature, before risky refactors, or when you'd want to rewind later.
  </Accordion>

  <Accordion title="Example workflow">
    ```bash theme={null}
    # 1. Enable Entire with Codex
    cd my-project
    entire agent add codex

    # 2. Start Codex
    codex

    # 3. Work with Codex
    # Ask it to make changes, edit files, and iterate

    # 4. Check status (in another terminal)
    entire status

    # 5. Rewind if needed
    entire checkpoint rewind

    # 6. Commit when ready
    git add .
    git commit -m "Add feature with Codex"

    # 7. Push to see on entire.io
    git push
    ```

    Your session is now visible on [entire.io](https://entire.io) with full context for code review.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Session not being captured">
    1. Verify Entire is enabled: `entire status`
    2. Check that `.codex/hooks.json` exists in the repository
    3. Ensure `.codex/config.toml` contains `codex_hooks = true`
    4. Ensure Codex is running from within the repository
  </Accordion>

  <Accordion title="No checkpoints created">
    1. Checkpoints require file changes — ensure Codex is modifying files
    2. Commit or stage work as part of your normal Git flow
    3. Check your settings in `.entire/settings.json`
    4. Verify Codex hooks were installed with `entire agent add codex`
  </Accordion>

  <Accordion title="Transcript not captured">
    1. Ensure Codex is writing rollout files in `~/.codex/` or your `CODEX_HOME`
    2. Verify the hook payload includes a transcript path
    3. Avoid ephemeral mode if you want full transcript capture
    4. Look for errors in Entire hook output with `entire doctor`
  </Accordion>
</AccordionGroup>