Codex - Entire

Prerequisites

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