@monotykamary/pi-better-grok 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 monotykamary
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,65 @@
+# pi-better-grok
+
+Better Grok/xAI for [pi](https://pi.dev) — mirrors the [pi-better-openai](https://github.com/monotykamary/pi-better-openai) UX for SuperGrok subscribers: fast mode, subscription usage in the footer, footer polish, and a settings picker.
+
+## Install
+
+```bash
+pi install git:github.com/monotykamary/pi-better-grok
+```
+
+## Commands
+
+| Command             | What it does                                                                                                                 |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `/grok-fast`        | Toggle fast mode (`reasoning_effort: "low"` injected into xAI provider payloads while enabled and the model is allow-listed) |
+| `pi --grok-fast`    | Start with fast mode enabled                                                                                                 |
+| `/grok-usage`       | Force-refresh and show SuperGrok subscription usage                                                                          |
+| `/grok-usage debug` | Show diagnostics (auth source, last fetch, config path)                                                                      |
+| `/grok-settings`    | Open the settings picker (footer, usage, fast mode)                                                                          |
+
+## Usage widget
+
+Piggybacks pi's native xAI login (`/login xai` → **Use a subscription**; tokens in `~/.pi/agent/auth.json` under `xai`). Falls back to `xai-oauth` / `xai-auth` auth-file entries and the official Grok CLI store at `~/.grok/auth.json`.
+
+Data comes from the same revision-pinned Grok subscription surface used by the community `pi-grok-usage` extensions:
+
+1. `GET https://cli-chat-proxy.grok.com/v1/user` (identity)
+2. `GET https://cli-chat-proxy.grok.com/v1/billing?format=credits` (with the `x-userid` header)
+
+Status widget line: `Usage: 66% left · ↺ 5d5h - Mon 5:34 PM` (weekly period + reset clock). Defaults to the widget area below the editor, like pi-better-openai; set `"footer": {"mode": "replace"}` for the full custom footer.
+
+## Configuration
+
+JSON config at `~/.pi/agent/extensions/pi-better-grok.json` (global) or `<project>/.pi/extensions/pi-better-grok.json` (project):
+
+```json
+{
+  "persistState": true,
+  "supportedModels": ["xai/grok-4.6", "xai/grok-4.5"],
+  "fast": { "effort": "low" },
+  "usage": {
+    "enabled": true,
+    "refreshIntervalMs": 60000,
+    "showOnlyOnSubscriptionModels": true,
+    "showResetTimes": true
+  },
+  "footer": { "mode": "status" }
+}
+```
+
+Unknown fields are preserved on write.
+
+## Roadmap
+
+- `/imagine` via `api.x.ai/v1/images/generations` (API-key accounts)
+- Live Search web tool (SuperGrok `x_search`)
+- Footer pets (port from pi-better-openai)
+
+## Acknowledgments
+
+Protocol contracts and prior art: [stnly/pi-grok](https://github.com/stnly/pi-grok), [puetsua/pi-grok-usage](https://github.com/puetsua/pi-grok-usage), [apoapostolov/pi-grok-usage](https://github.com/apoapostolov/pi-grok-usage), [luxus/pi-xai](https://github.com/luxus/pi-xai). See `THIRD_PARTY_NOTICES.md`.
+
+## Security
+
+The `cli-chat-proxy.grok.com` surface is unofficial and reverse-engineered from the Grok CLI; treat schema drift as expected. This extension never logs or stores token contents and masks account IDs in diagnostics.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,19 @@
+# Third-party notices
+
+This project's xAI/Grok subscription contract (endpoints, headers, and payload
+shapes) was established by prior MIT-licensed work in the pi ecosystem. The
+following projects were used as protocol references:
+
+- **stnly/pi-grok** — OAuth 2.0 + PKCE / device-flow provider, cli-chat-proxy
+  header parity (`x-grok-client-*`, `X-XAI-Token-Auth`, `x-authenticateresponse`).
+  MIT License. Copyright (c) stnly.
+- **puetsua/pi-grok-usage** — identity-first billing lookup
+  (`GET /v1/user` → `GET /v1/billing?format=credits` with `x-userid`) and the
+  `UsageSnapshot` contract this extension mirrors. MIT License.
+- **apoapostolov/pi-grok-usage** — Grok CLI `~/.grok/auth.json` reuse and
+  powerbar integration patterns. MIT License.
+- **luxus/pi-xai** — Grok Build billing/usage surface (`BillingUsage`) and
+  xAI imagine/video/web tooling references. MIT License.
+
+All trademarks belong to their respective owners. These projects are not
+affiliated with or endorsed by xAI.