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]

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

git clone <this repo> && cd grok-web-sdk
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"

grok login

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

{
  "mcpServers": {
    "grok": { "command": "/absolute/path/to/.venv/bin/grok", "args": ["mcp"] }
  }
}

claude mcp add grok -- /absolute/path/to/.venv/bin/grok mcp

grok serve --port 8000
# POST /chat/messages · POST /imagine/images · POST /imagine/videos · GET /health

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

from grok_web_sdk import grok_context, BrowserlessConfig
with grok_context(BrowserlessConfig(url="ws://host:3000", token="…")) as ctx:
    ...

.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)