codex-quota-widget

tiny bridge + scriptable widget for merged codex quotas from cliproxyapi.

merge multiple codex accounts into one home-screen view with unified 5-hour and weekly quota windows.

---

quick start

run the bridge on the machine that runs cliproxyapi:

git clone https://github.com/Microck/codex-quota-widget.git
cd codex-quota-widget

CLIPROXY_MANAGEMENT_KEY="your-management-password" \
CODEX_QUOTA_WIDGET_TOKEN="$(openssl rand -hex 18)" \
CODEX_QUOTA_WIDGET_HOST="127.0.0.1" \
node server.mjs

or create a local env file:

cp .env.example .env
$EDITOR .env

if your phone reaches the machine over tailscale, bind the bridge to that tailscale address:

CLIPROXY_MANAGEMENT_KEY="your-management-password" \
CODEX_QUOTA_WIDGET_TOKEN="<your-widget-token>" \
CODEX_QUOTA_WIDGET_HOST="100.x.y.z" \
node server.mjs

open:

http://100.x.y.z:8765/quota?token=<your-widget-token>

---

start at boot

install the systemd service on the machine that runs cliproxyapi:

cp .env.example .env
perl -0pi -e "s/replace-with-output-of-openssl-rand-hex-18/$(openssl rand -hex 18)/" .env
$EDITOR .env
./install-startup-service.sh

the installer writes codex-quota-widget.service to /etc/systemd/system, starts it immediately, and enables it for multi-user.target.

the generated service:

• reads bridge configuration from the ignored local .env
• starts after network ordering and cliproxyapi.service
• includes Tailscale ordering for hosts that bind to a Tailscale address
• restarts every 10 seconds if the bridge exits while dependencies finish starting

check it later with:

systemctl status codex-quota-widget.service --no-pager

---

ios widget

install Scriptable, paste scriptable-widget.js, and set:

const QUOTA_URL = "http://100.x.y.z:8765/quota?token=<your-widget-token>";

then add a Scriptable widget to the home screen and select the script.

the script asks ios to refresh the widget every 5 minutes. ios may still delay home-screen widget refreshes.

---

what it reads

the bridge uses cliproxyapi management endpoints:

• GET /v0/management/auth-files
• POST /v0/management/api-call

for every enabled codex auth, it calls:

https://chatgpt.com/backend-api/wham/usage

the widget shows merged 5-hour and weekly windows, ready/blocked account counts, and refill times.

tokens, auth file paths, and the management password are not returned by the bridge.