## Prerequisites

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

## Enable

```
    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.

## 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.

## 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                              |

## 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 [`checkpoint rewind` command reference](https://docs.entire.io/cli-reference/checkpoint#checkpoint-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 [`session resume` command reference](https://docs.entire.io/cli-reference/sessions#session-resume) for full flag documentation.

**Explain commits.** Inspect any commit or checkpoint with `entire checkpoint explain`. See the [`checkpoint explain` command reference](https://docs.entire.io/cli-reference/checkpoint#checkpoint-explain) for full flag documentation.

## 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.**

## 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.

## Example workflow

```
    # 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](/content/site-root.html) with full context for code review.

## Troubleshooting

### 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

### 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`

### 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`