GrokAuto 🤖

Ubuntu/Debian automation for grok.com via Chrome DevTools Protocol (CDP).

GrokAuto is a headless browser automation system that performs configurable chat actions on grok.com using Chrome/Chromium. It validates dependencies, checks your login state, executes tasks, captures responses, and provides comprehensive diagnostic feedback — all from the command line or on a schedule via Cron.

---

Features

• ✅ Dependency Checking — Validates Chrome, Python, pip packages, Xvfb, cron, and profile health
• ✅ Config Validation — JSON schema validation with colour-coded reports
• ✅ Login Detection — Automatically verifies your grok.com session before running
• ✅ Headless Execution — Runs without a GUI using Chromium's --headless=new mode
• ✅ Task Filtering — Run all tasks or filter by --task-id
• ✅ Cron Integration — One-command scheduling: --setup-cron "0 9 * * *"
• ✅ Markdown Output — Responses saved as timestamped .md files with restrictive permissions
• ✅ Comprehensive Logging — Colour-coded console output + file logging

---

Quick Start

1. Clone & Setup

git clone https://github.com/yourname/grokauto.git
cd grokauto
bash setup.sh

2. Log in to grok.com (one-time)

chromium --remote-debugging-port=9222
# Navigate to https://grok.com and sign in
# Close the browser — GrokAuto will reuse the saved session

3. Run a test

python3 main.py --diagnose
python3 main.py --prompt "Say hello and confirm automation works"

4. Schedule tasks

# Run all tasks from config every 10 minutes
python3 main.py --setup-cron "*/10 * * * *"

# Run only a specific task
python3 main.py --setup-cron "*/10 * * * *" --task-id gmail_check

---

Requirements

• OS: Ubuntu 22.04+ / Debian 12+
• Python: 3.8+
• Browser: Google Chrome or Chromium
• Packages: websocket-client, requests
• Optional: xvfb (for virtual display), cron (for scheduling)

---

Installation

Automated

bash setup.sh

This will:

1. Create ~/.config/grokauto/ and ~/grokauto_outputs/
2. Generate a default config.json
3. Check all dependencies and offer fixes
4. Create a grokauto wrapper in ~/.local/bin/

Manual

pip3 install websocket-client requests
mkdir -p ~/.config/grokauto ~/grokauto_outputs
cp config.json.template ~/.config/grokauto/config.json
# Edit config.json with your settings

---

Configuration

Edit ~/.config/grokauto/config.json:

{
  "chrome_profile_path": "/home/YOURUSER/.config/chromium/Default",
  "chrome_binary": "/usr/bin/chromium",
  "debug_port": 9222,
  "headless": true,
  "xvfb_display": ":99",
  "output_dir": "/home/YOURUSER/grokauto_outputs",
  "tasks": [
    {
      "id": "task_001",
      "prompt": "What are the latest developments in AI?",
      "wait_for_complete": true,
      "timeout_seconds": 120
    }
  ]
}

Task Properties

Field	Type	Description
id	string	Unique task identifier
prompt	string	The message sent to Grok
wait_for_complete	boolean	Wait for streaming response to finish
timeout_seconds	int	Maximum time to wait for a response

---

Usage

# Full system diagnostic
python3 main.py --diagnose

# Run all tasks from config
python3 main.py --run

# Run a specific task only
python3 main.py --run --task-id task_001

# Single inline prompt
python3 main.py --prompt "Explain quantum computing"

# Validate config file
python3 main.py --validate-config

# Check dependencies
python3 main.py --check-deps

# List saved outputs
python3 main.py --list-outputs

# Install cron job
python3 main.py --setup-cron "0 9 * * *"

# Remove cron job
python3 main.py --remove-cron

---

Output Files

All responses are saved as Markdown in your configured output_dir:

~/grokauto_outputs/
├── grok_response_task_001_20260523_143022.md
├── grok_batch_20260523_150000.md
└── ...

Each file contains:

• Task ID and timestamp
• Execution status (SUCCESS / TIMEOUT / ERROR)
• Duration
• Original prompt
• Grok's response

---

Architecture

Cron Scheduler ──► main.py (orchestrator)
                        │
                        ├──► deps_checker.py
                        ├──► config_validator.py
                        ├──► browser_ctl.py (CDP / WebSocket)
                        ├──► login_validator.py
                        ├──► task_executor.py
                        └──► response_writer.py

---

Security

See SECURITY.md for the full security review, threat model, and deployment checklist.

Key points:

• Chrome profile credentials are never modified or extracted
• CDP port binds to localhost only (127.0.0.1)
• Output files are created with chmod 600
• No credentials are stored in config files

---

Troubleshooting

Issue	Solution
"Not logged in to grok.com"	Launch Chromium manually, go to grok.com, and sign in
"Port 9222 is already in use"	Kill existing Chrome: kill $(lsof -t -i:9222)
"No Chrome or Chromium found"	sudo apt install -y chromium-browser
Missing pip packages	pip3 install websocket-client requests
Headless mode fails	Set "headless": false and run inside a VNC session

---

Contributing

See CONTRIBUTING.md for guidelines.

---

License

MIT

---

Disclaimer

GrokAuto is an unofficial automation tool. Use it responsibly and in accordance with grok.com Terms of Service. The authors are not responsible for account actions resulting from automated usage.