Codex Caffeinate

A tiny Codex hook plugin that keeps a Mac and its display awake while Codex is actively working.

It starts /usr/bin/caffeinate -di when a turn begins and releases the process as soon as the turn stops. The display may sleep normally again while Codex is waiting for the next prompt.

How it works

• UserPromptSubmit starts a session-scoped caffeinate -di process.
• Stop terminates the process when the Codex turn finishes.
• SessionEnd performs fallback cleanup.
• Concurrent Codex sessions use separate processes and do not interfere with each other.
• PID and process-identity data are stored under PLUGIN_DATA; the plugin never uses pkill and will not deliberately terminate an unrelated caffeinate process.
• Non-macOS systems are detected and left unchanged.

-d prevents display sleep, while -i prevents idle system sleep. Combining them keeps both the display and the Mac awake for the duration of the turn.

Requirements

• macOS
• Codex with lifecycle hooks support
• /usr/bin/python3

Install locally

Clone the plugin into your personal plugin directory:

git clone https://github.com/qiudeng7/codex-caffeinate.git ~/plugins/codex-caffeinate

Add the following entry to the plugins array in ~/.agents/plugins/marketplace.json:

{
  "name": "codex-caffeinate",
  "source": {
    "source": "local",
    "path": "./plugins/codex-caffeinate"
  },
  "policy": {
    "installation": "AVAILABLE",
    "authentication": "ON_INSTALL"
  },
  "category": "Productivity"
}

Install it from the personal marketplace:

codex plugin add codex-caffeinate@personal

Start a new Codex conversation, open /hooks, review the three commands, and trust them. Codex skips local hooks until their current definitions have been trusted.

Development

The hook controller uses only the Python standard library. To exercise it manually, provide a Codex-style hook event on standard input and a temporary writable PLUGIN_DATA directory.

License

MIT