Get QuotaPerch
onto its perch.

Before you begin

Version 0.8.0 was checked on 14 October 2026: 80 Swift tests pass, the app compiles for Intel and Apple silicon, and live quota/credit decoding passes on Intel. Read the 0.8.0 release record.

• A Mac running macOS 13 or later. This Mac app does not run on iPhone, iPad or Windows.
• Apple Command Line Tools or Xcode, with Swift 5.9 or later for the included tests.
• Your own compatible official Codex native executable, already installed and signed in with your ChatGPT account. A subscription or browser login alone is not enough.
• Setup opens in Terminal, but you do not need to type build commands. You answer simple y/N prompts. A signed drag-and-drop installer is on hold; the current option builds from source on your Mac.

Apple-silicon execution, Developer ID signing, notarisation and clean-Mac installation remain outstanding. Universal compilation alone does not establish that every Mac has been tested.

1. Download and unpack

Download the source preview above, then double-click the ZIP in Finder. You should see a folder named QuotaPerch, containing README.md, Sources and scripts. Read the README and the scripts before running them.

The download checksum is available in sha256sums.txt. Use the browser fingerprint checker if you want to compare it. A matching checksum checks the bytes, not whether the software is safe.

2. Double-click to start setup

Inside the extracted QuotaPerch folder, double-click Build and Install.command. It opens a guided setup in Terminal. Type y and press Return to accept a step; press Return on its own to decline.

Setup checks macOS and Apple’s build tools. If the tools are missing, it offers to open Apple’s free Command Line Tools installer. Complete Apple’s dialogue, then run Build and Install.command again. No paid Apple Developer membership is needed to build your own copy. About Apple’s build tools.

If macOS blocks the command file, use the Mac warning guidance below for the named file. Stop for damage or malware warnings.

3. Follow the progress

Setup shows four stages: check, build, verify and install, then open. Compilation can take several minutes. Keep the window open and do not start a second installer.

• Already have this version? Setup tells you and lets you keep it without rebuilding.
• QuotaPerch is running? Setup prepares the replacement first, then asks whether it may close the installed copy. You can cancel without replacing it.
• Updating? The existing app is saved in a separate backup folder before replacement. Preferences and Codex login files are left alone.

The app installs into ~/Applications/QuotaPerch.app. Setup does not ask for sudo or change Mac security settings.

4. Find the app—or get help

When setup finishes, look for QuotaPerch in the menu bar at the top of the screen, not the Dock. Press Return to close the setup window.

If something fails, the window explains the next step and shows the location of a saved setup log inside the source folder’s build/install-logs directory. Review it before sharing with robin@robsaitools.com; logs may contain local file paths. If installation succeeded but opening failed, follow the first-launch guidance below.

bash scripts/install-local.sh

5. If macOS blocks the first launch

Only proceed if you trust the source and are confident the app has not been altered. For a developer-verification or notarisation warning, Apple provides an exception for that individual app:

1. Try opening QuotaPerch once in Finder.
2. Open System Settings → Privacy & Security, then scroll to Security.
3. If the warning names the QuotaPerch file you just tried to open, select Open Anyway, authenticate if asked, and confirm Open.

This does not notarise the app. If the warning says it is damaged or will harm your computer, stop and contact Rob. If the option is missing on a managed Mac, contact your administrator. Do not disable Gatekeeper globally or remove quarantine attributes. Read Apple’s explanation of Mac app warnings.

If the script reports an opening error after installation, use Finder → Go → Go to Folder and enter ~/Applications. Open QuotaPerch.app from there. These steps also apply if Rob has separately supplied a trusted prebuilt preview; this website currently supplies source only.

6. Connect and check your first reading

Look for QuotaPerch in the menu bar at the top of your screen. It is a menu-bar utility, so there may be no big welcome window.

1. Open its panel and choose Review Codex connection.
2. Review the displayed native executable before approving. Version 0.8.0 can discover the native binary inside known official npm packages. If it is not found, use Choose Codex in settings. Shell and Node launchers are not executed.
3. Refresh and compare weekly allowance and remaining credits with the official usage dashboard at approximately the same time. Settings → Show in menu bar offers weekly, credits, or both. Automatic reload remains “Status unavailable”; check its switch in the official dashboard.
4. Keep history and notifications off unless you want them. Enable Open at login only after confirming the app works.

Q — means a reading is unavailable; it is not zero. A stale marker means the last reading could not be refreshed. If the older QuotaBar is still running, quit it manually to avoid two menu-bar items.

Updating or removing the preview

To update from source, repeat these steps with the new source folder. Setup asks before closing the installed copy and backs it up before replacement. To remove it, turn off Open at login, clear optional history if desired, quit the app, then move ~/Applications/QuotaPerch.app to the Bin. Leave your Codex installation and login files alone.

When a signed and notarised release is available, the Downloads page will identify it. You can then replace the preview with that release.