codex-cmux

real-time cmux sidebar integration for OpenAI Codex CLI. status pills, progress bars, bash command logs, focus-aware desktop notifications, git integration — all wired through codex's 5 hook events and cmux's unix socket.

sibling project to cmux-claude-pro (16 hooks for Claude Code). same architecture, adapted for codex's simpler hook system.

adaptive estimation using n/(n+K) where K learns from your session history:

1 tool  → ████░░░░░░░░░░░░░░░░  0.09
3 tools → ██████████░░░░░░░░░░  0.23
5 tools → ████████████░░░░░░░░  0.33
done    → ████████████████████  1.00 Complete

caps at 0.95 during work. never hits 100% until codex actually finishes.

every bash command gets a formatted log entry:

[codex] [info] Bash: `npm test -- --coverage` → exit 0
[codex] [info] Bash: `git diff --stat` → exit 0
[codex] [info] Bash: `ls -la src/` → exit 0

when codex adds Edit/Read/Grep tool hooks, those will log automatically too (future-proofed with a default passthrough).

focus-aware — only fires when you're NOT looking at the codex tab:

every codex lifecycle event we handle:

codex's hook system is simpler. these claude code features have no codex equivalent:

rm -rf /tmp/codex-cmux && cd /tmp && git clone https://github.com/yigitkonur/codex-cmux.git && cd codex-cmux && npm install && npm run build && bash install.sh

the installer automatically:

• copies handler to ~/.codex-cmux/
• enables codex_hooks = true in ~/.codex/config.toml
• writes 5 hook events to ~/.codex/hooks.json (preserving existing hooks)
• creates a backup at hooks.json.codex-cmux-backup
• verifies handler loads and Stop is silent
• works on macOS and Linux (uses python3, no sed)

# 1. clone
git clone https://github.com/yigitkonur/codex-cmux.git
cd codex-cmux

# 2. build (needs node 20+)
npm install
npm run build

# 3. install
bash install.sh

# 4. restart codex

npx codex-cmux setup

TUI wizard with feature selection, SSH setup, and remote deployment.

the installer handles this automatically. for manual setup, create ~/.codex/hooks.json:

{
  "hooks": {
    "SessionStart": [{"matcher": "startup|resume|clear", "hooks": [{"type": "command", "command": "node ~/.codex-cmux/handler.cjs", "timeout": 10}]}],
    "PreToolUse": [{"matcher": "Bash", "hooks": [{"type": "command", "command": "node ~/.codex-cmux/handler.cjs", "timeout": 10}]}],
    "PostToolUse": [{"matcher": "Bash", "hooks": [{"type": "command", "command": "node ~/.codex-cmux/handler.cjs", "timeout": 10}]}],
    "UserPromptSubmit": [{"hooks": [{"type": "command", "command": "node ~/.codex-cmux/handler.cjs", "timeout": 10}]}],
    "Stop": [{"hooks": [{"type": "command", "command": "node ~/.codex-cmux/handler.cjs", "timeout": 10}]}]
  }
}

and enable hooks in ~/.codex/config.toml:

[features]
codex_hooks = true

restart codex after adding hooks.

paste this into a fresh codex session:

run this test step by step. wait 2 seconds between each step and announce each step number.

step 1 — run: echo "hello from codex-cmux sidebar test"
step 2 — run: ls -la /tmp/
step 3 — run: echo "step 3 done" && date
step 4 — run: git status 2>/dev/null || echo "not a git repo"
step 5 — run: echo "all 5 steps complete — check your cmux sidebar!"

~/.codex-cmux/config.json:

{
  "features": {
    "statusPills": true,
    "progress": true,
    "logs": true,
    "notifications": true,
    "gitIntegration": true
  },
  "notifications": {
    "onStop": true,
    "onError": true
  }
}

both can run in the same cmux workspace simultaneously:

each gets its own status pill, progress bar, and log entries in the sidebar.

when you ssh into a remote machine and run codex there, codex-cmux updates your local sidebar with the remote session's status.

local cmux sidebar ← unix socket ← SSH -R tunnel ← remote handler ← codex hooks

local machine — add to ~/.zshrc:

if [ -S "$CMUX_SOCKET_PATH" ]; then
  ln -sf "$CMUX_SOCKET_PATH" /tmp/cmux-local.sock 2>/dev/null
fi

local machine — add to ~/.ssh/config:

Host myserver
  RemoteForward /tmp/cmux-fwd.sock /tmp/cmux-local.sock
  SendEnv CMUX_WORKSPACE_ID CMUX_SURFACE_ID CMUX_TAB_ID CMUX_PANEL_ID

remote machine:

# accept env vars + allow socket reuse
echo "AcceptEnv CMUX_WORKSPACE_ID CMUX_SURFACE_ID CMUX_TAB_ID CMUX_PANEL_ID" | sudo tee -a /etc/ssh/sshd_config
echo "StreamLocalBindUnlink yes" | sudo tee -a /etc/ssh/sshd_config
sudo systemctl restart sshd  # Linux
# or: sudo launchctl kickstart -k system/com.openssh.sshd  # macOS

# deploy handler
scp ~/.codex-cmux/handler.cjs myserver:~/.codex-cmux/

# add to remote ~/.zshrc:
if [ -S /tmp/cmux-fwd.sock ] && [ -n "$SSH_CONNECTION" ]; then
  export CMUX_SOCKET_PATH=/tmp/cmux-fwd.sock
  [ -z "$CMUX_WORKSPACE_ID" ] && [ -f /tmp/cmux-fwd.env ] && . /tmp/cmux-fwd.env
fi

or use the interactive installer: codex-cmux setup handles SSH config automatically.

a single 29KB node.js handler (handler.cjs) gets invoked for every hook event. reads JSON from stdin, updates cmux's sidebar via direct unix socket (~8ms per call), manages state atomically in /tmp/codex-cmux/.

no daemon. no background process. no runtime dependencies. just node builtins.

codex hook event
    → stdin JSON
    → handler.cjs (route by hook_event_name)
    → unix socket → cmux sidebar
    → atomic state file write
    → exit 0 (always, NEVER produces stdout on Stop)

critical design rule: the Stop handler MUST be completely silent. any JSON on stdout would be interpreted by codex as a "continue the turn" directive. the handler updates the sidebar and exits without writing anything.

codex has no SessionEnd hook. cleanup works via:

1. ppid liveness — on each SessionStart, scan all session state files. if the stored codex parent PID is dead (kill(pid, 0) → ESRCH), clear that session's sidebar and delete its state.
2. cmux crash recovery — set_agent_pid registers the PID. cmux's 30-second poller detects dead PIDs and auto-clears the status pill.
3. age-based fallback — state files older than 24 hours are cleaned on SessionStart.

~/.codex-cmux/
├── handler.cjs    # 29KB compiled handler (5 events)
└── config.json    # feature toggles

/tmp/codex-cmux/
└── <session-id>.json  # per-session state (atomic r/w, mkdir lock)

source layout:

src/
├── handler.ts           # entry: stdin → route → dispatch → exit 0 (5 events)
├── constants.ts         # AGENT_KEY='codex', paths, limits
├── cmux/
│   ├── socket.ts        # unix socket client (send/fire/fireAll + isFocused)
│   ├── commands.ts      # typed builders for 14 cmux primitives
│   └── helpers.ts       # fireStatus, statusCmd, notifyIfUnfocused
├── state/
│   ├── manager.ts       # atomic file state with mkdir locking + ppid detection
│   ├── types.ts         # SessionState, StatusPhase (5 phases)
│   └── progress.ts      # adaptive n/(n+K) algorithm
├── events/
│   ├── context.ts       # HandlerContext interface
│   ├── types.ts         # 5-event discriminated union
│   ├── session.ts       # SessionStart + stale ppid cleanup
│   ├── tools.ts         # PreToolUse + PostToolUse (Bash)
│   └── flow.ts          # UserPromptSubmit + Stop (silent)
├── features/
│   ├── status.ts        # 5-state priority system
│   ├── logger.ts        # bash command log formatting
│   └── git.ts           # branch detection, PR extraction
├── config/              # types, loader, defaults
├── installer/           # TUI wizard, TOML editor, hooks.json merge
└── util/                # env detection, stdin reader

# 1. remove hooks from hooks.json (keeps your other hooks)
python3 -c "
import json, os
p = os.path.expanduser('~/.codex/hooks.json')
if not os.path.exists(p): exit()
d = json.load(open(p))
for event in list(d.get('hooks', {})):
    d['hooks'][event] = [e for e in d['hooks'][event]
                         if not any('codex-cmux' in h.get('command','')
                                    for h in e.get('hooks', []))]
    if not d['hooks'][event]: del d['hooks'][event]
json.dump(d, open(p, 'w'), indent=2)
print('removed codex-cmux hooks')
"

# 2. remove handler files
rm -rf ~/.codex-cmux/

# 3. restart codex

or use the interactive uninstaller: codex-cmux uninstall

MIT