cmux-codex-autoapprove

cmux Codex Autoapprove

Canonical files:

• Skill root: $HOME/.claude/skills/cmux-codex-autoapprove
• Worker script: $HOME/.claude/skills/cmux-codex-autoapprove/scripts/cmux_codex_approve_launchd.py
• LaunchAgent: $HOME/Library/LaunchAgents/com.$USER.cmux-codex-approve.plist
• Plist backup: ~/.claude/skills/cmux-codex-autoapprove/com.$USER.cmux-codex-approve.plist

Install / Restore

On a new machine, copy the plist and load it:

cp ~/.claude/skills/cmux-codex-autoapprove/com.$USER.cmux-codex-approve.plist \
   ~/Library/LaunchAgents/com.$USER.cmux-codex-approve.plist
launchctl load ~/Library/LaunchAgents/com.$USER.cmux-codex-approve.plist

PATH requirement: The plist must include $HOME/bin in PATH (where cmux lives). Current plist already has this.

• Logs: $HOME/.claude/supervisor/cmux-codex-launchd.log
• State: $HOME/.claude/supervisor/cmux-codex-launchd-state.json

Compatibility paths:

• Wrapper path used by older flows: $HOME/.claude/bin/cmux_codex_approve_launchd.py
• Codex skill symlink: $HOME/.codex/skills/cmux-codex-autoapprove

Purpose

Use this skill for a custom cmux auto-approver that:

• enumerates terminal surfaces with cmux --json tree --all
• reads visible terminal content with cmux read-screen
• filters for approval-like prompts near the bottom of the live screen
• asks codex exec for a one-token decision: ENTER, 1, y, SKIP, or DENY
• sends the chosen key back with cmux send or cmux send-key

This is the non-snap-agent-supervisor path.

Normal Workflow

1. Verify the target surface with:

cmux --json tree --all
cmux read-screen --workspace <workspace> --surface <surface> --lines 24

2. If you need a one-shot run, execute:

/opt/homebrew/bin/python3 $HOME/.claude/skills/cmux-codex-autoapprove/scripts/cmux_codex_approve_launchd.py

3. For the scheduled agent, use:

launchctl kickstart -k gui/501/com.$USER.cmux-codex-approve
launchctl print gui/501/com.$USER.cmux-codex-approve

Behavior Notes

• The worker intentionally focuses on the bottom active region of the screen so stale scrollback does not retrigger approvals forever.
• Approved prompt digests are cleared once the surface returns to a normal shell or idle prompt.
• Idle runs are cheap. codex exec is only called when the screen looks like a real approval dialog.

When To Edit

Edit the worker script when:

• a real approval dialog is missed
• a non-approval surface is being auto-approved
• launchd can detect candidates but hangs or times out during classification
• prompt wording changes and the regexes need to expand

Pattern wiring rule (mandatory): Detection regexes in this worker are checked at two call sites — is_approval_candidate() (the gate) and heuristic_decision() (the action). A pattern added to heuristic_decision() but not is_approval_candidate() will silently fail because the gate drops it first. When adding a detection regex or phrase, you MUST add test strings to both functions. The test file at scripts/test_approval_patterns.py enforces this by running every dialog through both functions — it will fail if a pattern is only wired into one.

Check these first when debugging:

• $HOME/.claude/supervisor/cmux-codex-launchd.log
• $HOME/.claude/supervisor/cmux-codex-launchd.stderr.log
• $HOME/.claude/supervisor/cmux-codex-launchd-state.json