README

A Grok (xAI) provider for Laravel Tackle — run your in-app AI coding agent on Grok models.

📚 Full documentation: tackle.jordandalton.com

AI_CODE_PROVIDER=grok

That's the whole switch. Every Tackle agent — ai:code, ai:run, ai:fix, ai:review, the self-healer — now runs on xAI's Grok models.

This is a laravel/ai provider under the hood, so it also works in any laravel/ai app without Tackle.

Two ways to authenticate

Mode	What it does	Status
`api-key`	Uses an xAI API key from console.x.ai against the public `api.x.ai` endpoint.	Recommended — xAI's documented path for CI/CD, automation, and custom apps.
`subscription`	Uses the session token from the Grok CLI's sign-in against the CLI backend, on your grok.com plan.	Best-effort — see the honest caveat.

GROK_AUTH selects the mode (auto by default: subscription when a Grok CLI sign-in exists, otherwise api-key). If you want the recommended path unconditionally, set GROK_AUTH=api-key.

Installation

The easiest path from a Tackle app:

php artisan tackle:install grok

Or via Composer directly:

composer require jordandalton/tackle-grok
php artisan vendor:publish --tag=tackle-grok-config   # optional

The service provider registers a grok driver with laravel/ai automatically — no config/ai.php edits required (add a 'grok' => ['driver' => 'grok'] entry if you prefer it explicit).

API-key mode (recommended)

Get a key from console.x.ai and set it:

GROK_AUTH=api-key
XAI_API_KEY=xai-...

This is the stock, documented xAI integration path — the same api.x.ai endpoint and API-key auth xAI publishes for building custom apps. Billing is metered per token, so pin rates in config/tackle.php under pricing.models to keep budget enforcement meaningful.

php artisan grok:status
php artisan ai:code --provider=grok --model=grok-4.6

Subscription mode: the honest version

Subscription mode runs the agents on your grok.com plan by reusing the Grok CLI's sign-in — the same ~/.grok/auth.json session token, sent to the CLI backend (cli-chat-proxy.grok.com).

What you should know before using it:

This mimics the official Grok CLI. The CLI backend rejects requests that don't identify as the CLI (HTTP 426, "your Grok CLI version is outdated"), so this mode sends the same client-version headers the Grok CLI sends. It is not a documented third-party integration path — xAI's documented paths for custom apps are the API and Agent mode/ACP. Treat subscription mode as best-effort.
xAI can change or gate it at any time. Every endpoint and header lives in config (GROK_BASE_URL, GROK_CLIENT_VERSION, …), so a change is an .env edit rather than a package release — but there is no guarantee it keeps working, and plan usage is subject to your grok.com subscription's terms.
The Grok CLI owns the session. This package reads the token read-only and never mints one. The CLI refreshes its own session in the background; when it lapses, run grok login.

If your usage matters, prefer api-key mode, or confirm subscription-backend use with xAI developer support first.

# Sign in once with the Grok CLI, then:
php artisan grok:status

  Mode ............................ subscription (plan-covered)
  Default model ................... grok-4.6
  Auth file ....................... /Users/you/.grok/auth.json
  Session token ................... valid, expires 2026-08-17 02:53 UTC

Configuration

Everything is env-tunable; publish the config for the full list:

Variable	Default	Description
`GROK_AUTH`	`auto`	`auto` \| `subscription` \| `api-key`
`XAI_API_KEY` / `GROK_API_KEY`	—	Key for api-key mode
`GROK_API_BASE_URL`	`https://api.x.ai/v1`	Endpoint for api-key mode
`GROK_AUTH_FILE`	`~/.grok/auth.json`	Grok CLI auth file (subscription mode)
`GROK_BASE_URL`	CLI backend	Endpoint for subscription mode
`GROK_MODEL`	`grok-4.6`	Default model in subscription mode
`GROK_CLIENT_VERSION`	`1.0.3`	Client-version header the CLI backend requires

Tackle integration

When subscription mode is active and grok is the active provider, the CLI backend's models are registered in Tackle's pricing catalog at $0/MTok — the budget tracker stays accurate because your plan covers usage. The zero rates apply only when this provider is active, so an api-key setup keeps real rates. A leftover claude-*/gpt-* model default from another provider is swapped for the Grok default automatically.

How it works

laravel/ai's xAI gateway already speaks the Responses API. This package extends it with a GrokProvider that:

in api-key mode, is the stock xAI provider — api.x.ai, Authorization: Bearer <key>, stock model defaults;
in subscription mode, swaps the bearer for the Grok CLI session token, points the base URL at the CLI backend, and (via GrokGateway) attaches the client-version headers that backend requires.

Development

composer install
./vendor/bin/pest
./vendor/bin/pint

License

MIT

jordandalton / tackle-grok

Maintainers

Package info

Statistics

Security