# grok-web-sdk

Drive **your own** Grok to generate content — text, images, video — from a local
AI agent, the command line, HTTP, or Python. It automates the grok.com web UI
using **your logged-in session**, so there's **no API key and no per-token cost**.

Runs locally by default: patchright drives a real Chrome on your machine (no
Docker). A Browserless backend is available for remote/scale use.

```mermaid
flowchart LR
  Agent[Local AI agent] -->|MCP| M[grok mcp]
  You -->|CLI| C[grok chat / image / video]
  M --> B[behaviours]
  C --> B
  B --> Chrome[local Chrome<br/>your logged-in Grok]
  Chrome --> Out[text · images · video → files]
```

## Install

**With pipx** (recommended — installs a global `grok` command in its own env):
```bash
pipx install grok-web-sdk         # once published to PyPI
# …or from a local checkout today:
pipx install ./grok-web-sdk
grok install-browser              # only if you don't have Google Chrome
```

**From source** (for development):
```bash
git clone <this repo> && cd grok-web-sdk
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
```

## Sign in once

```bash
grok login
```

A Chrome window opens — log into your Grok account, press Enter. The session
persists in a local profile (`~/.grok-web-sdk/profile`), so you only do this
once (repeat if it ever expires).

## Use it

**CLI**
```bash
grok chat "explain quantum tunneling in one paragraph"
grok image "a red teapot on the moon" --aspect 16:9 --count 4 -o ./out
grok video "a paper plane looping" --res 720p --duration 10s -o ./out
```
Image/video files are downloaded to `./downloads` (or `-o <dir>`) and the paths
are printed.

**MCP (local AI agents)** — expose Grok as tools to Claude Desktop, Claude Code,
Cline, Cursor, etc.

Claude Desktop (`claude_desktop_config.json`):
```json
{
  "mcpServers": {
    "grok": { "command": "/absolute/path/to/.venv/bin/grok", "args": ["mcp"] }
  }
}
```
Claude Code:
```bash
claude mcp add grok -- /absolute/path/to/.venv/bin/grok mcp
```
Tools: `grok_chat`, `grok_generate_image`, `grok_generate_video` — image/video
tools return the saved file paths.

**HTTP API**
```bash
grok serve --port 8000
# POST /chat/messages · POST /imagine/images · POST /imagine/videos · GET /health
```

**Python**
```python
from grok_web_sdk import grok_context, send_message, generate_image, generate_video

with grok_context() as ctx:                      # local backend by default
    print(send_message(ctx, "hello").response)
    img = generate_image(ctx, "a red teapot", aspect_ratio="1:1", count="4")
    print(img.files)                             # downloaded paths
```

## Capabilities

| Surface | Options |
|---|---|
| Chat | prompt → reply (+ reasoning header) |
| Image | `quality` Speed/Quality · `aspect_ratio` 2:3·3:2·1:1·9:16·16:9 · `count` Auto·4·8·12 |
| Video | `resolution` 480p·720p · `duration` 6s·10s · `aspect_ratio` |

## Remote backend (optional)

To run against a Browserless container instead of local Chrome:
```python
from grok_web_sdk import grok_context, BrowserlessConfig
with grok_context(BrowserlessConfig(url="ws://host:3000", token="…")) as ctx:
    ...
```
From a datacenter IP you'll also need a **residential proxy** (`proxy=` on the
config) — Cloudflare weighs IP reputation separately from browser fingerprint.

## Tests

```bash
.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest                                          # unit + contract, no browser; live tier auto-skips
GROK_PROFILE_DIR=spike/.profile .venv/bin/pytest -m live  # read-only live tier (needs a logged-in profile)
```

## Notes

- **Your account, your rules.** This automates the web UI with your session;
  that likely runs against xAI's ToS. Use a dedicated/throwaway account if you're
  cautious, and keep request rates sane.
- **Local-first & private.** Everything runs on your machine; the session profile
  and downloads never leave it.
- Architecture: `core` → `pages` (L1) → `behaviours` (L2) → `api` (MCP/HTTP/CLI),
  enforced by import-linter.