init

README.md

@@ -0,0 +1,159 @@
+# Codex Usage Monitor for Waybar
+
+A Waybar custom module that displays your Codex 5-hour and weekly rate-limit usage, plus the 5-hour reset countdown.
+
+Default display:
+
+```text
+5H 22% · W 18% · 2h55m
+```
+
+It reads usage through the installed Codex CLI's `account/rateLimits/read` app-server method. It does not read or transmit raw authentication tokens.
+
+## Requirements
+
+- Codex CLI logged in with ChatGPT
+- Python 3.11 or newer
+- Waybar with custom module support
+
+## Install
+
+Install the commands without changing Waybar:
+
+```bash
+./install.sh
+```
+
+Install and configure the module in a selected Waybar section:
+
+```bash
+./install.sh --configure-waybar --section right --restart
+```
+
+The configurator backs up `config.jsonc` and `style.css`, preserves JSONC comments, avoids duplicate module entries, and aborts if it cannot identify the requested module section safely.
+
+## Manual Waybar Setup
+
+Add `custom/codex-usage` to any one of `modules-left`, `modules-center`, or `modules-right`.
+
+Add this module definition to `~/.config/waybar/config.jsonc`:
+
+```jsonc
+"custom/codex-usage": {
+  "exec": "codex-waybar",
+  "return-type": "json",
+  "interval": 60,
+  "tooltip": true
+}
+```
+
+Then restart Waybar:
+
+```bash
+omarchy restart waybar
+```
+
+## Formatting
+
+Formatting is configured in Waybar's `exec` command, like other custom module command options:
+
+```jsonc
+"custom/codex-usage": {
+  "exec": "codex-waybar --format '5H {five_hour_used}% | W {weekly_used}% | {five_hour_reset_in}'",
+  "return-type": "json",
+  "interval": 60
+}
+```
+
+Available placeholders:
+
+| Placeholder | Meaning |
+| --- | --- |
+| `{five_hour_used}` | 5-hour usage percentage |
+| `{weekly_used}` | Weekly usage percentage |
+| `{five_hour_reset_in}` | Time remaining until the 5-hour reset |
+| `{weekly_reset_in}` | Time remaining until the weekly reset |
+| `{five_hour_reset_at}` | Local 5-hour reset date and time |
+| `{weekly_reset_at}` | Local weekly reset date and time |
+| `{plan}` | ChatGPT plan reported by Codex |
+
+Other command options:
+
+```text
+--tooltip-format TEMPLATE
+--warning PERCENT       default: 70
+--critical PERCENT      default: 90
+--timeout SECONDS       default: 10
+--no-cache
+```
+
+## Styling
+
+The command emits these Waybar CSS classes:
+
+- `normal`
+- `warning`
+- `critical`
+- `stale`: the live refresh failed and cached data is displayed
+- `unavailable`: no live or cached data is available
+
+Example:
+
+```css
+#custom-codex-usage {
+  margin: 0 7.5px;
+}
+
+#custom-codex-usage.warning {
+  color: #d8a657;
+}
+
+#custom-codex-usage.critical,
+#custom-codex-usage.unavailable {
+  color: #a55555;
+}
+
+#custom-codex-usage.stale {
+  opacity: 0.65;
+}
+```
+
+## Troubleshooting
+
+Run the module directly. It always prints Waybar-compatible JSON:
+
+```bash
+codex-waybar | jq
+```
+
+If it reports unavailable usage, confirm that `codex` is installed and logged in:
+
+```bash
+codex login status
+```
+
+The last valid response is cached at `${XDG_CACHE_HOME:-~/.cache}/codex-waybar/rate-limits.json`. The cache contains rate-limit percentages and reset timestamps, not credentials.
+
+## Development
+
+Run the tests:
+
+```bash
+python -m unittest discover -s tests -v
+```
+
+Run directly from the repository:
+
+```bash
+./bin/codex-waybar | jq
+```
+
+## Uninstall
+
+Remove the installed commands:
+
+```bash
+rm ~/.local/bin/codex-waybar ~/.local/bin/codex-waybar-configure
+```
+
+Remove `custom/codex-usage` from your Waybar module list and module definition, then remove its CSS rules.