Codex Click Guide

A native macOS overlay that turns an assistant handoff into a clear visual and spoken click target.

What it does

• Draws a high-contrast pulsing target above every app.
• Speaks the requested action with the macOS system voice.
• Lets clicks pass through to the real control underneath.
• Dismisses automatically after a click or timeout.
• Maps screenshot coordinates correctly across Retina and scaled displays.
• Supports explicit display selection for multi-monitor screenshots.
• Rejects ambiguous or off-display targets instead of showing a misleading marker.
• Runs entirely on the Mac with no network service or analytics.

Install

Requirements: macOS, Xcode Command Line Tools, and Swift.

./install.sh

The installer builds the executable and places it at ~/.local/bin/codex-guide.

Use

~/.local/bin/codex-guide \
  --x 2200 \
  --y 1440 \
  --source-width 2560 \
  --source-height 1664 \
  --display-id 1 \
  --text "Click Approve" \
  --seconds 30

Coordinates use the source screenshot's top-left origin. Pass the screenshot dimensions with --source-width and --source-height so the guide can translate them to the current display. On a Mac with multiple matching displays, pass the target CoreGraphics display ID with --display-id. List active display IDs and bounds with:

~/.local/bin/codex-guide --list-displays

If exactly one display is active, or exactly one active display matches the screenshot aspect ratio, --display-id can be omitted. Ambiguous, inactive, and off-screen targets fail without showing an overlay. If coordinates are omitted, the guide highlights the current mouse pointer.

Test

./test.sh

The native Swift test runner verifies Retina scaling, secondary-display origins, aspect matching, and invalid-coordinate rejection.

Design

The program is a single Swift source file built on AppKit, AVFoundation, and CoreGraphics. It uses an always-on-top transparent panel, a pulsing target animation, native speech synthesis, and a global click monitor.

Privacy

Click Guide does not upload screenshots, record clicks, or make network requests. Spoken guidance uses the voice installed on the Mac.