pi-xai-supergrok

An OAuth provider extension for pi that lets you use your SuperGrok (grok.com) or X Premium+ subscription with pi — no XAI_API_KEY required. You log in once through the browser (or a device code), and pi refreshes the token automatically.

It registers a provider called supergrok. Models are discovered live from GET https://api.x.ai/v1/models whenever credentials are available, so new grok-* ids appear without editing the extension. A static fallback catalog is used when discovery can't run (pre-login, offline, 403, …).

Unofficial. Not affiliated with xAI. Reuses the public Grok-CLI OAuth client_id (a public client, not a secret) because xAI only accepts loopback OAuth from allowlisted clients. The consent screen may say "Grok Build" / "Grok CLI".

Requirements

• pi installed
• An active SuperGrok subscription on your xAI account, or an X Premium+ subscription on the X account you sign in with

⚠️ xAI may return HTTP 403 for some SuperGrok tiers even after a successful browser login. In that case use an API key with pi's built-in xai provider (export XAI_API_KEY=xai-...).

Install

# from npm (after publish)
pi install npm:pi-xai-supergrok

# from git
pi install git:github.com/preinpost/pi-xai-supergrok

# from a local checkout
pi install /path/to/pi-xai-supergrok

# one-shot without writing settings
pi -e npm:pi-xai-supergrok

Security: pi packages run with full system access. Review the source before installing third-party packages.

Then restart pi (or start a new session). Confirm the provider is loaded:

pi --list-models | grep supergrok

Usage

Inside pi:

/login supergrok

Pick a login method:

• Browser (this machine) — opens accounts.x.ai and captures the code on http://127.0.0.1:56121/callback. Best on your own laptop/desktop.
• Device code — for headless / SSH / container hosts. pi prints a URL and a short code; open the URL on any device, enter the code, approve. Only enter the code on an official xAI page.

After login, select a grok-* model and chat. Credentials are stored in ~/.pi/agent/auth.json and refreshed in the background.

Refresh the model list

Models are re-fetched automatically after a successful login. To force a re-discovery later:

/supergrok-refresh-models

How it works

Item	Value
Provider id	supergrok
Auth	OAuth 2.0 + PKCE (authorization-code with loopback, or RFC 8628 device code)
client_id	public Grok-CLI client (not a secret)
API base	https://api.x.ai/v1 (OpenAI-compatible → openai-completions)
Model source	live GET /v1/models (chat models only), else static fallback

Model discovery

On extension load the factory (async):

1. Resolves a bearer token from XAI_API_KEY, or from ~/.pi/agent/auth.json → supergrok.access (if not expired).
2. Calls GET https://api.x.ai/v1/models.
3. Keeps chat/completion models (drops grok-imagine-* image/video generators).
4. Maps xAI price fields into pi's $/MTok cost shape.
5. Infers reasoning / vision support from the model id and price fields.

If no token is available or the request fails, the built-in fallback list is registered instead. After /login supergrok the live catalog is re-fetched and the provider is re-registered so the new models show up without restarting pi.

Env-var fallback

The provider also honors XAI_API_KEY. If it's set, you can use supergrok models without OAuth at all, and discovery uses the same key.

Uninstall

pi remove npm:pi-xai-supergrok
# or
pi remove git:github.com/preinpost/pi-xai-supergrok

Package layout

pi-xai-supergrok/
  index.ts            # extension entry (async factory)
  provider.ts         # registerProvider wiring
  oauth.ts            # PKCE browser + device-code + refresh
  models.ts           # live /v1/models discovery
  fallback-models.ts  # offline / pre-login catalog
  constants.ts        # endpoints, client_id, scopes
  package.json        # pi.extensions manifest

License

MIT