samihalawa/grokbot

⚡ 10-Second Quickstart

# 1. Install globally (or use npx grokbot)
npm install -g grokbot

# 2. Add your Grok session cookie (or export GROK_SSO=...)
grokbot pool add --name primary --sso "<sso_cookie>"

# 3. Ask anything with live token streaming
grokbot ask "Explain the Paxos consensus algorithm in 2 sentences"

🏗️ Architecture & Topology

⚡ Comparison

🚀 Core Features

1. Multi-Account Parallel Pooling & Failover

Pool multiple accounts into one high-throughput cluster. If an account hits HTTP 429 or quota exhaustion, grokbot triggers a 15-minute cooldown and instantly serves the prompt from the next healthy account with zero dropped jobs.

# Add accounts (static tokens or dynamic 1Password references)
grokbot pool add --name coder --sso "<token>" --roles coding
grokbot pool add --name legal --op-id "op_item_id" --roles filing,legal

# Check real-time cluster health
grokbot pool status

2. Parallel Batch Processing (grokbot batch)

Process hundreds of prompts concurrently across your account pool:

grokbot batch prompts.jsonl --concurrency 4 --output results.jsonl

Automatically balances load across accounts and pauses rate-limited nodes without stopping the batch.

3. 3-Layer Exporter (~78% Fewer Tokens)

Recovers transcripts across Grok's 3 distinct storage layers:

1. Local Persistent Slices (sand-client-persistence) — offline replica turns.
2. Web App Chat REST API (/rest/app-chat) — user threads and response trees.
3. Gateway Roster — live bot transcripts.

# Export to clean, token-efficient Markdown
grokbot export --format markdown --output ~/grok_archive.md

# Calculate token savings on any prompt file
grokbot tokens ~/grok_archive.md

Note

Token Benchmark: 8.85 MB of raw JSON (~2.21M tokens) formats into 1.92 MB of clean Markdown (~480k tokens) — saving ~78% context window overhead.

4. Local OpenAI Proxy & Web Dashboard (grokbot serve)

Spin up a local OpenAI-compatible server at http://127.0.0.1:8000/v1:

grokbot serve --port 8000

• Web Dashboard: Open http://localhost:8000/ to inspect real-time account quotas and test prompts interactively.
• Cursor / Claude Code / Codex: Set Base URL to http://127.0.0.1:8000/v1 and use model grok-3 or grok-3-deepsearch.
• Python / Node.js SDK:

import OpenAI from 'openai';
const client = new OpenAI({ baseURL: 'http://127.0.0.1:8000/v1', apiKey: 'ignored' });

const res = await client.chat.completions.create({
  model: 'grok-3',
  messages: [{ role: 'user', content: 'Design a distributed lock in Redis' }],
  stream: true,
});
for await (const chunk of res) process.stdout.write(chunk.choices[0]?.delta?.content || '');

5. Native WebSocket Bot Agent Orchestration (grokbot agent)

Direct programmatic orchestration over native Node.js WebSocket to wss://grok.com/ws/bot/?uid=${uid} with zero external relays or Python scripts:

# List agent roster and group memberships across accounts
grokbot agent roster [account]

# Tail recent agent transcript entries in real-time
grokbot agent tail <account> <agentId> [limit]

# Send a prompt instruction directly to a bot's session
grokbot agent prompt <account> <agentId> "Review latest filings"

# Execute raw JSON-RPC 2.0 command over bot gateway
grokbot agent call <account> <method> [paramsJson]

6. Native MCP Server (Claude Code & Cursor)

Expose Grok tools directly to AI pair programmers via Model Context Protocol:

{
  "mcpServers": {
    "grokbot": {
      "command": "npx",
      "args": ["grokbot", "mcp"]
    }
  }
}

📖 Commands Cheatsheet

📄 License

MIT © Sami Halawa