# QuotaPerch — guide Updated 14 October 2026. QuotaPerch source candidate 0.8.0. A calm setup, a clear reading, and help when the numbers look odd. ## Before you start This is a source-code release candidate for evaluation, not the public installer. It targets macOS 13 or later, Intel and Apple silicon, and needs your own compatible official Codex native executable with a ChatGPT-backed login. Source building also needs Apple Command Line Tools. Intel validation has passed. Apple-silicon execution and public release checks remain. For detailed installation commands and first-launch help, visit https://robsaitools.com/quotaperch/install/. ## Quick start 1. **Check the release label.** Start on Downloads. For this candidate, read the source README and scripts before building. The normal signed installer will appear only after release checks pass. 2. **Double-click guided setup.** Extract the source ZIP and open Build and Install.command inside its QuotaPerch folder. Setup checks your Mac and Apple’s free build tools, shows progress and asks before closing an installed copy. Type y and press Return to accept a prompt; Return alone declines. If it offers Apple’s tool installer, finish that installation and run setup again. A setup log is saved for troubleshooting. No paid Apple Developer membership is needed for a local build. 3. **Review the connection.** Open the menu-bar panel and choose Review Codex connection. Confirm the displayed native executable is the official one you installed before approving. If it is not found, open settings → Choose Codex and select the genuine native binary. 4. **Compare the first reading.** Check main weekly against your official Usage dashboard at approximately the same time. Other windows are separate. Missing or stale readings must not be treated as fresh. 5. **Keep the defaults quiet.** Five-minute refresh, hidden email and no saved history are the starting settings. Enable history or notifications only when useful. Pause stops automatic refresh; manual Refresh remains available. ## Worked example Example: main weekly is 22%; Other window five-hour is 0%. The menu bar reads Q 22% in its default weekly mode. Other window can still be unavailable. If the last refresh then fails, the old value gains a stale marker rather than changing to 100%. ## Troubleshooting ### Q — Review the connection and official login. No bucket is guessed. ### Reading is stale Refresh once; check connection and last-successful time. Do not hammer refresh. ### Connection changed Confirm a genuine Codex update, then approve its new fingerprint. ### Possible conflict or high CPU Pause, then Quit QuotaPerch. Leave other apps alone. Report a redacted summary and versions. ### Mac security warning For a trusted copy, see https://robsaitools.com/quotaperch/install/#mac-warning for Apple’s app-specific Open Anyway steps. Stop for damage or malware warnings. Do not disable Gatekeeper or strip quarantine. ### What exactly appears in my menu bar? By default it is the main weekly Codex allowance. For example, main weekly 22% and Other window five-hour 0% still produces Q 22%. Open the panel to see the separate windows. This is not a promise that every model can currently run. ### Why can Other window be blocked when the menu bar still shows plenty? Each reported allowance is a separate gate. The default menu-bar display stays on main weekly; you can select credits or both in settings. Check the Other window windows and official provider dashboard for Other window access; QuotaPerch cannot remove a block. ### Does 50% mean half a week of working time? No. It means half of that reported allowance remains. It does not tell you how many tasks, minutes or tokens you can use. The app does not invent a credit-to-percentage conversion. ### Can this app reset my quota or buy extra credits? No. Its request list contains only initialisation, account read and rate-limit read. It has no task-submission, payment or reset-redemption function. Use the provider’s own controls for account changes. ### Does refreshing consume AI task quota? QuotaPerch does not submit an AI task. It asks the existing Codex helper for account and rate-limit information. We do not control provider accounting or guarantee that future provider rules will stay unchanged. Five-minute refresh is the default; there is a pause switch. ### What does the little dot after the percentage mean? Q 22% · means the last reading is stale. The panel also labels stale data. A failed refresh never silently turns a previous reading into a new one. Check the last-successful time before relying on it. ### Why does it show Q — or main weekly unavailable? The main weekly source was missing or ambiguous, or the connection has not been approved. The app refuses to substitute a different bucket. Review the connection first, then check your official login. Only use the source override when you know exactly which bucket is yours. ### Why must I review the Codex executable? The utility starts a native executable already on your Mac. It asks you to approve its path and file fingerprint first, and asks again after a change. This catches unexpected replacement after approval; it does not prove that an initially selected file is genuine. Only approve the official binary you installed. ### Why did my normal Codex update trigger another review? An update changes the executable’s bytes. That is expected, but QuotaPerch still pauses before running the changed file. Check that you performed the update through the official source, then approve the new connection. ### Why is my codex command rejected even though it works in Terminal? It may be a shell or Node launcher rather than the native binary. This candidate deliberately rejects scripts. Choose the native binary supplied by the official CLI package or compatible extension. Do not approve an arbitrary file just because it is named codex. ### What permissions and account details does it need? The app itself does not request Full Disk Access, Accessibility or screen recording. Login and provider networking are handled by your approved Codex helper. The helper may have its own permissions and behaviour. Do not paste passwords or authentication files into support messages. ### Is local history private? History is off by default. When enabled it stores up to seven days of account-wide readings in your own Application Support folder, with restrictive file permissions and a pseudonymous account fingerprint. It is not encrypted. Turning history off or clearing it removes the history file, not any separate exports you already saved. ### Can history prove that one task used a particular amount? No. An 82% to 53% change is 29 percentage points between two account-wide observations. Other work or delayed provider updates may contribute. The app labels reset boundaries separately and does not call a quota change proof of incorrect billing. ### Why has a reset time passed but the reading has not changed? The displayed time came from the provider. Reaching it is not proof of renewed access. Refresh once, check the official dashboard and follow provider support guidance. Do not repeatedly start jobs just to test the limit. ### What happens if the provider response changes? Unrecognised, oversized or invalid data is rejected. You may see an unavailable or stale state rather than a guessed value. There is no silent downgrade to a less trustworthy source. ### How do I stop or uninstall it? Turn off Open at login in QuotaPerch or macOS Login Items, disable or clear local history, then Quit. Remove QuotaPerch.app from your own Applications folder. For a full local cleanup, use Finder → Go → Go to Folder and open ~/Library/Application Support/QuotaPerch. Remove only that app folder after checking it; do not remove ~/.codex or other apps’ files. ### Is there a normal public Mac installer yet? Not in this release candidate. The download is source code and build scripts for evaluation. A universal Intel and Apple silicon installer will appear only after Apple-silicon testing, Developer ID signing, notarization and a clean-Mac installation check are complete. Never disable Gatekeeper to work around this status. ## Safety Source candidate, not a signed public Mac release. Verify important outcomes and use official provider controls. No software is hack-proof or immune to conflicts. Nothing here excludes rights or remedies that cannot lawfully be excluded. ## New in 0.8.0 Remaining spendable credits appear separately from plan percentages and manual resets. Settings → Show in menu bar offers weekly allowance, credit balance, or both. Unknown balances remain “Not reported”; positive balances below one credit display “<1”. Automatic reload is **Status unavailable**: the Codex interface does not supply that setting. Check it in the official usage dashboard. QuotaPerch cannot switch it or buy credits. Automatic-refresh pause now survives relaunch. Known npm native binaries are discovered without running their JavaScript launchers, and the existing executable approval remains mandatory. Credit balances are not saved in optional history. They are included in a support summary only when you choose to copy or export it. Review exports before sharing. 80 Swift tests and Intel live quota/credit decoding passed. Universal compilation passed; Apple-silicon execution, Developer ID signing, notarisation and clean-Mac release checks remain.