tanshilongmario/codex-light-shortcut/build-codex-status-light

Build Codex Status Light

Create a reliable global status light using Codex hooks and Apple Shortcuts. Track each Codex session independently and aggregate with waiting > working > completed.

Workflow

1. Confirm macOS and inspect existing files before changing anything:

• ~/.codex/hooks.json
• ~/.codex/config.toml
• ~/.codex/codex-light/
• The project-local equivalents, if present

1. Run /usr/bin/shortcuts list and confirm these shortcuts, or map the user's equivalents:

• Codex-执行中
• Codex-等待
• Codex-完成

1. Read references/architecture-and-diagnostics.md before changing an existing implementation or diagnosing concurrency.
2. Copy scripts/codex-light-hook to an absolute, stable location such as ~/.codex/codex-light/codex-light-hook and make it executable.
3. Merge the following handlers into the active hook layer without deleting unrelated hooks:

• SessionStart → codex-light-hook reset
• UserPromptSubmit → codex-light-hook working
• PermissionRequest → codex-light-hook waiting
• PostToolUse → codex-light-hook working
• Stop → codex-light-hook completed

1. Use absolute command paths in hook configuration. Preserve existing configuration and user changes.
2. Ask the user to review new or changed hooks through /hooks. Never bypass trust or edit trusted hashes directly.
3. Run scripts/test-state-priority.sh before testing physical lights.
4. Trigger the three shortcuts directly, one at a time, when the user has authorized a real light test. Finish on Codex-完成 unless requested otherwise.
5. Validate one real approval flow and inspect state/events.log to confirm another task's working events cannot replace an active waiting state.

Hook configuration shape

Use one matcher group per event. Omit matcher to cover every supported tool:

{
  "hooks": {
    "SessionStart": [{"hooks": [{"type": "command", "command": "/ABSOLUTE/PATH/codex-light-hook reset", "timeout": 3}]}],
    "UserPromptSubmit": [{"hooks": [{"type": "command", "command": "/ABSOLUTE/PATH/codex-light-hook working", "timeout": 3}]}],
    "PermissionRequest": [{"hooks": [{"type": "command", "command": "/ABSOLUTE/PATH/codex-light-hook waiting", "timeout": 3}]}],
    "PostToolUse": [{"hooks": [{"type": "command", "command": "/ABSOLUTE/PATH/codex-light-hook working", "timeout": 3}]}],
    "Stop": [{"hooks": [{"type": "command", "command": "/ABSOLUTE/PATH/codex-light-hook completed", "timeout": 3}]}]
  }
}

Safety and verification

• Treat Apple Shortcut execution as a real external side effect; announce it before testing.
• Use an isolated temporary CODEX_HOME and /usr/bin/true for logic tests.
• Do not overwrite hooks.json blindly. Merge and validate JSON.
• Do not kill arbitrary processes. Only stop a PID after verifying its command belongs to shortcuts run Codex-....
• Launch shortcut animations asynchronously so hooks never delay a Codex turn.
• Report the observed aggregate and per-session states, not only command exit codes.

Diagnosis order

1. Confirm the task is actually waitingOnApproval.
2. Check state/events.log for PermissionRequest/waiting.
3. Check state/sessions/<session-id> and state/current.
4. Check hook enablement and trust with /hooks.
5. Check shortcut names and run the waiting shortcut directly.
6. Check state/shortcut.log and the recorded PID.

If the task is waiting but no waiting event exists, diagnose hook coverage, trust, or whether the approval predates hook loading. If a waiting event exists but current becomes working while another task remains pending, replace last-event-wins state with per-session aggregation.