Codex Integration

Codex integration uses a notify hook for turn completion and PTY mode for message delivery.

Message Delivery

Automatic (PTY mode only): Messages are delivered via PTY injection when agent goes idle. Manual (vanilla mode): Agent must poll for messages using hcom listen. Why PTY only?

Codex has only one hook: codex-notify (turn completion)
No hook fires when agent goes idle (unlike Claude/Gemini)
PTY wrapper detects idle and injects messages

Hook Installation

Hooks are installed to ~/.codex/config.toml and policies to ~/.codex/rules/hcom.rules.

Automatic Install

Run Codex via hcom launcher:

hcom codex

Hooks are installed automatically on first launch.

Manual Install

If you prefer to run Codex directly:

hcom hooks add codex

Then restart Codex for hooks to activate.

Verify Installation

hcom status
# Look for: [✓] codex

hcom hooks status
# Shows hook configuration details

Launch Modes

PTY Mode (Required for Automatic Messages)

Launch with hcom for automatic message delivery:

# Single instance in current terminal
hcom codex

# Multiple instances in new windows
hcom 3 codex

# With initial prompt
hcom codex --hcom-prompt "Start by checking hcom list"

# With tag for grouping
hcom codex --tag backend

PTY mode features:

Automatic message delivery via terminal injection
Terminal screen capture (hcom term)
Automatic cleanup on kill (hcom kill)
Fork and resume support

Vanilla Mode (Manual Polling)

Run Codex directly after installing hooks:

codex

Inside the session, connect to hcom:

hcom start

Vanilla mode behavior:

Hook tracks turn completion only
No automatic message delivery
Agent must poll: hcom listen or hcom events
Binding happens at notify hook via transcript marker

Example workflow: In vanilla Codex:

# Connect to hcom
hcom start

# Poll for messages
hcom listen 10

# Or use events
hcom events --agent self --type message

Hook Types

Codex has 1 hook type:

Hook	When	Purpose
codex-notify	Agent turn completes	Update status to listening, trigger PTY delivery

Payload format:

{
  "type": "agent-turn-complete",
  "thread-id": "uuid",
  "turn-id": "12345",
  "cwd": "/path/to/project",
  "input-messages": ["user prompt"],
  "last-assistant-message": "response text",
  "transcript_path": "/path/to/transcript.jsonl"
}

Hook behavior:

Parse JSON from argv[2]
Resolve instance via thread-id or process binding
Update status to listening
Set idle_since timestamp
Notify PTY wrapper via TCP wake

Configuration

Default Arguments

hcom config codex_args "--search"

Merged with launch-time args (launch args win on conflict).

System Prompt

hcom config codex_system_prompt "You are a backend engineer."

Or via environment:

export HCOM_CODEX_SYSTEM_PROMPT="Your role..."

Sandbox Mode

hcom config codex_sandbox_mode off

Auto-Approval (Execpolicy)

Codex uses execpolicy rules for auto-approval. Enable auto-approval:

hcom config auto_approve 1

This creates ~/.codex/rules/hcom.rules:

# hcom integration - auto-approve safe commands
prefix_rule(pattern=["hcom", "send"], decision="allow")
prefix_rule(pattern=["hcom", "list"], decision="allow")
prefix_rule(pattern=["hcom", "events"], decision="allow")
prefix_rule(pattern=["hcom", "listen"], decision="allow")
prefix_rule(pattern=["hcom", "transcript"], decision="allow")
prefix_rule(pattern=["hcom", "status"], decision="allow")
prefix_rule(pattern=["hcom", "config"], decision="allow")
prefix_rule(pattern=["hcom", "relay"], decision="allow")
prefix_rule(pattern=["hcom", "archive"], decision="allow")
prefix_rule(pattern=["hcom", "claude", "--help"], decision="allow")
prefix_rule(pattern=["hcom", "gemini", "-h"], decision="allow")
# ... more rules

Rule format:

prefix_rule() matches command prefix
decision="allow" auto-approves
Priority handled by Codex

Transcript Path Derivation

Codex transcript path is derived from thread-id: Path pattern: $CODEX_HOME/sessions/**/rollout-*-{thread_id}.jsonl Search logic:

Use CODEX_HOME env var or ~/.codex default
Glob search for rollout-*-{thread_id}.jsonl
Return most recently modified match

Why this matters:

Transcript path not always in notify payload
Needed for vanilla binding
Auto-derived when missing

Session Binding

PTY Mode

Binding happens at notify hook:

HCOM_PROCESS_ID env var present
Bind thread-id to process
Update directory, session_id, transcript_path
Set listening status
Notify PTY wrapper

Vanilla Mode

Binding happens via transcript marker search:

Run hcom start inside Codex
Output contains [hcom:instance-name] marker
Notify hook searches transcript for marker
Binds thread-id to instance automatically

Transcript search:

fn find_last_bind_marker(transcript_path: &str) -> Option<String>

Reads last 50KB of transcript
Searches for [hcom:name] pattern
Returns instance name if found

Launch Examples

Single Agent

# Current terminal
hcom codex

# New window
hcom 1 codex

# With initial prompt
hcom codex --hcom-prompt "Check hcom list"

Multiple Agents

# 3 agents in new windows
hcom 3 codex

# Tagged group
hcom 3 codex --tag api

# With sandbox mode
hcom codex --sandbox danger-full-access

Fork and Resume

# Fork active or stopped agent
hcom f luna

# Resume stopped agent
hcom r luna

PTY Injection

Codex message delivery works differently than Claude/Gemini: Why no hook-based delivery?

Codex only has turn-complete hook
No hook fires when agent is idle
Can’t inject messages via hook output

How PTY delivery works:

Notify hook sets status to listening
Notify hook writes idle_since timestamp
Notify hook sends TCP wake to PTY wrapper
PTY wrapper detects idle state
PTY wrapper injects messages via terminal
Codex sees injected text at next prompt

TranscriptWatcher:

Monitors transcript file for changes
Detects idle by lack of activity
Alternative to hook-based detection

Manual Polling (Vanilla Mode)

Since vanilla mode has no automatic delivery, agents must poll:

Using listen

# Block until message arrives (60s default)
hcom listen

# With timeout
hcom listen 10

# With filters
hcom listen --from nova

Using events

# Check for messages
hcom events --type message --agent self --last 5

# Wait for specific event
hcom events --wait --from nova

Loop polling

while true; do
  hcom listen 60 && break
  echo "No messages, waiting..."
  sleep 5
done

Advanced

Hook Command Format

config.toml:

notify = ["hcom", "codex-notify"]

Codex spawns: hcom codex-notify '{json_payload}' Payload passed as argv[2].

Stale Command Detection

hcom detects stale hook commands (e.g., /old/path/hcom) and auto-updates:

setup_codex_hooks() checks existing notify line
If contains codex-notify but path differs
Removes old line and re-adds with current path
Preserves other config settings

Orphaned Process Recovery

If Codex process is orphaned (no session binding):

hcom start --orphan <name-or-pid>

Recreates identity from pidtrack.

Troubleshooting

Messages not arriving (PTY mode)

Check Codex is idle: hcom list shows listening status
Verify PTY wrapper running: ps aux | grep hcom | grep pty
Check idle_since timestamp: hcom list <name> idle_since
Try manual wake: hcom send @codex-instance -- test

Messages not arriving (vanilla mode)

Expected behavior. Vanilla Codex must poll manually:

hcom listen 10

Hooks not working

# Re-install hooks
hcom hooks remove codex
hcom hooks add codex

# Restart Codex

Transcript path not found

Check CODEX_HOME env var
Verify transcript exists: ls ~/.codex/sessions/*/rollout-*.jsonl
Check thread-id in hook payload

Config.toml has existing notify

hcom refuses to overwrite non-hcom notify hooks:

notify = ["other-tool", "other-hook"]

Error: “config.toml already has a notify hook configured” Solution: Remove other notify hook or use separate Codex install.

Reference

Hook configuration: ~/.codex/config.toml Policy configuration: ~/.codex/rules/hcom.rules Config path function:

pub fn get_codex_config_path() -> PathBuf
pub fn get_codex_rules_path() -> PathBuf

Transcript derivation:

pub fn derive_codex_transcript_path(thread_id: &str) -> Option<String>

Notify handler:

pub fn handle_codex_notify(args: &[String]) -> i32

Getting Started

Core Concepts

Guides

Integration

Advanced

​Codex Integration

​Message Delivery

​Hook Installation

​Automatic Install

​Manual Install

​Verify Installation

​Launch Modes

​PTY Mode (Required for Automatic Messages)

​Vanilla Mode (Manual Polling)

​Hook Types

​Configuration

​Default Arguments

​System Prompt

​Sandbox Mode

​Auto-Approval (Execpolicy)

​Transcript Path Derivation

​Session Binding

​PTY Mode

​Vanilla Mode

​Launch Examples

​Single Agent

​Multiple Agents

​Fork and Resume

​PTY Injection

​Manual Polling (Vanilla Mode)

​Using listen

​Using events

​Loop polling

​Advanced

​Hook Command Format

​Stale Command Detection

​Orphaned Process Recovery

​Troubleshooting

​Messages not arriving (PTY mode)

​Messages not arriving (vanilla mode)

​Hooks not working

​Transcript path not found

​Config.toml has existing notify

​Reference

Build docs developers (and LLMs) love

Codex Integration

Message Delivery

Hook Installation

Automatic Install

Manual Install

Verify Installation

Launch Modes

PTY Mode (Required for Automatic Messages)

Vanilla Mode (Manual Polling)

Hook Types

Configuration

Default Arguments

System Prompt

Sandbox Mode

Auto-Approval (Execpolicy)

Transcript Path Derivation

Session Binding

PTY Mode

Vanilla Mode

Launch Examples

Single Agent

Multiple Agents

Fork and Resume

PTY Injection

Manual Polling (Vanilla Mode)

Using listen

Using events

Loop polling

Advanced

Hook Command Format

Stale Command Detection

Orphaned Process Recovery

Troubleshooting

Messages not arriving (PTY mode)

Messages not arriving (vanilla mode)

Hooks not working

Transcript path not found

Config.toml has existing notify

Reference