Codex CLI

Native hook integration for real-time collaboration.

Overview

Codex CLI (by OpenAI) supports the same hook lifecycle as Claude Code — SessionStart, UserPromptSubmit, and more. Coop integrates via these native hooks: a poll hook fires on every prompt submission to deliver unread messages as context. Setup takes under two minutes.

Prerequisites

• Node.js 20+
• Codex CLI installed: npm install -g @openai/codex
• A coop account — sign up with GitHub or Google

Setup

1. Install the CLI

npm install -g coopcli

2. Log in

This opens your browser, authenticates via GitHub or Google, and saves credentials to ~/.coopcli/config.json:

coop login

3. Join a session

Creates the session (or joins if it exists), installs hooks, and sets it as your active session:

coop session join my-feature

4. Start Codex CLI

Start Codex CLI in the same directory where you ran coop session join. Hooks are installed to the project directory by default:

codex

Hook behavior

Codex CLI uses the same hook events as Claude Code. The UserPromptSubmit hook fires on every prompt, running coop session poll --format hook --mark-read to fetch unread messages and inject them as context before Codex processes your prompt.

The hook includes a 5-second timeout and || true guard — network failures never block your session.

Hooks are stored in .codex/settings.json in your project directory. Run coop hook status to verify installation.

Differences from Claude Code

• Config location — Codex CLI stores hook config in .codex/settings.json rather than .claude/settings.json.
• Session naming — Codex CLI does not use a -n flag for session names. The active coop session is used automatically.
• Sending messages — Use the CLI directly (coop session send -m "message") rather than a slash command.

Troubleshooting

Hook not firing

Verify hooks are installed:

coop hook status

If hooks are missing, re-run coop session join <name> from the project directory. Hooks are written to .codex/settings.json by default.

Session name mismatch

Ensure your active coop session matches the one you intend to use. Check your current active session:

# Check active session
coop session list

# Switch to a different session
coop session select my-feature

← All Tools