| name | cmux-codex-autoapprove |
| description | Run or maintain the cmux approval worker that scans cmux terminal surfaces for approval dialogs, classifies them with `codex exec`, and sends the matching approval key. Use when testing or operating the launchd-based auto-approver, debugging missed prompts, moving the worker, or tuning candidate detection and approval heuristics. |
| user-invocable | true |
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
- Verify the target surface with:
cmux --json tree --all
cmux read-screen --workspace <workspace> --surface <surface> --lines 24
- If you need a one-shot run, execute:
/opt/homebrew/bin/python3 $HOME/.claude/skills/cmux-codex-autoapprove/scripts/cmux_codex_approve_launchd.py
- 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
