Skip to main content
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

​
How It Works

Entire integrates with Codex through project-level hook configuration in .codex/hooks.json. When you enable Entire with the Codex agent, the hooks are installed automatically: 
entire enable --agent codex
That command also enables Codex’s required hooks feature flag by writing codex_hooks = true to .codex/config.toml, so you do not need to configure that manually. 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

​
Captured Data

DataDescription
ConversationFull transcript of prompts and responses
File changesFiles modified via apply_patch in Codex rollouts
Token usageInput, cached-input, output, and reasoning tokens
TimestampsSession, turn, and checkpoint timing

​
Features

​
Rewind Support

Rewind to previous checkpoints during or after a Codex session: 
# Interactive mode
entire rewind

# Or rewind to a specific checkpoint
entire rewind --to <checkpoint-id>

# List available rewind points
entire rewind --list
FlagDescription
--to <commit>Rewind to specific commit ID (non-interactive)
--listList available rewind points (JSON output)
--logs-onlyOnly restore logs, don’t modify working directory
--resetReset branch to commit (destructive)
When you rewind, Entire restores the checkpointed transcript state and shows the command to continue the Codex session.

​
Resume Previous Sessions

Resume a previous Codex session by switching to its branch: 
entire resume <branch>
This command:
  1. Checks out the specified branch
  2. Finds the session ID from commits unique to this branch
  3. Restores the session log if it does not exist locally
  4. Shows the command to resume the session (for Codex, codex resume <session-id>)
FlagDescription
-f, --forceResume from older checkpoint without confirmation

​
Explain Commits

View or generate explanations of how code was written: 
# Explain a specific commit
entire explain --commit abc1234

# Explain a specific checkpoint
entire explain --checkpoint a3b2c4d5

# Show full transcript
entire explain --full
FlagDescription
-c, --checkpoint <id>Explain a specific checkpoint (ID or prefix)
--commit <sha>Explain a specific commit (SHA or ref)
--fullShow full parsed transcript (all prompts/responses)
-s, --shortShow summary only (omit prompts and files)

​
Important Caveats

  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.

​
Best Practices

​
Enable Codex Through Entire

Use entire enable --agent 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
  • When you’d want to rewind later

​
Example Workflow

# 1. Enable Entire with Codex
cd my-project
entire enable --agent 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 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

  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
  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 enable --agent codex
  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

​
Limitations

  • The integration is in preview and may have rough edges
  • Subagent capture is not available
  • PreToolUse is currently shell-only and is not used for lifecycle tracking
  • Transcript capture depends on Codex writing rollout JSONL files