Skip to content

README.md

Latest commit

 

History

History
95 lines (65 loc) · 3.68 KB

README.md

File metadata and controls

95 lines (65 loc) · 3.68 KB
Raw

Codex Usage Lock Screen Widget

A compact Scriptable Lock Screen widget that shows the percentage remaining in your Codex usage windows:

IMG_3227

The Mac refreshes the data every 15 minutes while awake. Scriptable syncs it to the iPhone through iCloud Drive.

Requirements

  • macOS and iPhone signed into the same iCloud account
  • Scriptable installed on the iPhone with iCloud enabled
  • ChatGPT or Codex desktop app installed in /Applications and signed in
  • Python 3 on Mac

This project uses the Codex executable bundled with the Codex (now inside ChatGPT) desktop app. It does not install or require a separate Codex CLI, and it does not copy or expose authentication tokens.

Install

  1. Open Scriptable once on the iPhone and enable iCloud for Scriptable.

  2. Clone this repository inside Codex and run:

    chmod +x install.sh
./install.sh

  3. If macOS asks, allow Terminal or Codex to access iCloud Drive and install the user LaunchAgent.

  4. On the iPhone, open Scriptable and run Codex Usage once.

  5. Long-press the Lock Screen, choose Customize, tap the widget area, add Scriptable, choose the rectangular widget, and select Codex Usage.

What gets installed

Item Location
Widget script ~/Library/Mobile Documents/iCloud~dk~simonbs~Scriptable/Documents/Codex Usage.js
Mac updater ~/.local/share/codex-usage-widget/codex_usage_to_icloud.py
Usage data Scriptable's iCloud folder as codex-limits.json
LaunchAgent ~/Library/LaunchAgents/com.openai.codex-usage-widget.plist
Logs /tmp/codex-usage-widget.log and /tmp/codex-usage-widget.err

The LaunchAgent uses StartInterval = 900, so it runs every 15 minutes while the Mac is awake. iOS controls the exact Lock Screen widget refresh time.

Verify

Run the updater manually:

~/.local/share/codex-usage-widget/codex_usage_to_icloud.py

Check the generated data and service:

ls -l "$HOME/Library/Mobile Documents/iCloud~dk~simonbs~Scriptable/Documents/codex-limits.json"
launchctl print "gui/$(id -u)/com.openai.codex-usage-widget"
tail -n 20 /tmp/codex-usage-widget.log
tail -n 20 /tmp/codex-usage-widget.err

Troubleshooting iCloud Drive access

If the installer or updater cannot access Scriptable's iCloud folder and reports Operation not permitted, allow the desktop app running Codex to access iCloud Drive:

  1. Open System Settings → Privacy & Security → Files & Folders.
  2. Select ChatGPT (or Codex, if shown separately).
  3. Enable iCloud Drive.
  4. Run the installer or updater again.

If no iCloud Drive toggle appears under Files & Folders, open System Settings → Privacy & Security → Full Disk Access, enable ChatGPT or Codex there, then retry.

The Scriptable folder used by this project is:

~/Library/Mobile Documents/iCloud~dk~simonbs~Scriptable/Documents

Display behavior

  • Percentages are percentage remaining, not percentage used.
  • 05H shows its local reset time only when Codex supplies one.
  • 07D shows its local reset date as DD.MM.
  • Missing reset information is omitted.

Uninstall

launchctl bootout "gui/$(id -u)" "$HOME/Library/LaunchAgents/com.openai.codex-usage-widget.plist" 2>/dev/null || true
rm -f "$HOME/Library/LaunchAgents/com.openai.codex-usage-widget.plist"
rm -rf "$HOME/.local/share/codex-usage-widget"
rm -f "$HOME/Library/Mobile Documents/iCloud~dk~simonbs~Scriptable/Documents/Codex Usage.js"

The uninstall commands intentionally leave codex-limits.json in place. Remove it separately if desired.