README.md

@@ -0,0 +1,40 @@
+# gibby
+
+Minimal multi-account Codex token aggregator.
+
+## Endpoints
+
+- `GET /health`
+- `GET /token`
+
+## OAuth helper
+
+Add accounts with:
+
+```bash
+uv run python scripts/oauth_helper.py --mode local
+uv run python scripts/oauth_helper.py --mode manual
+```
+
+By default the helper stores accounts in `data/accounts.json` and does not replace the current active account.
+
+## Run
+
+```bash
+uv sync
+uv run uvicorn gibby.app:app --host 0.0.0.0 --port 8080
+```
+
+## Environment
+
+- `DATA_DIR` default: `data`
+- `GIBBY_BIND_HOST` default: `0.0.0.0`
+- `GIBBY_PORT` default: `8080`
+- `GIBBY_CALLBACK_HOST` default: `127.0.0.1`
+- `GIBBY_CALLBACK_PORT` default: `1455`
+- `GIBBY_OAUTH_CLIENT_ID` default: `app_EMoamEEZ73f0CkXaXp7hrann`
+- `GIBBY_ORIGINATOR` default: `opencode`
+
+## State format
+
+The service stores tokens and last known cooldown information in JSON. Accounts already known to be in cooldown are skipped without re-checking usage until their cooldown expires.