An autonomous AI bot that plays GeoGuessr the way a human would.
Multi-agent computer vision • Human-like behavior • Zero page injection
I wanted to explore what AI is truly capable of today - not just answering questions, but actually seeing and reasoning about the real world. AIguessr was built entirely using Claude Code as both the development tool and the AI brain behind the bot. It's a demonstration of how far multi-agent vision systems have come, and what happens when you give an AI eyes and a GeoGuessr account.
This project is for educational and research purposes only. Using bots or automation tools in GeoGuessr violates their Terms of Service. By using this software, you accept full responsibility for your account and any consequences, including bans. The author is not responsible for any actions taken against your account.
This is not a script that intercepts network traffic or extracts coordinates from API responses. AIguessr uses multi-agent AI vision to study each panorama and make an educated guess - just like a real player would.
| Traditional Scripts | AIguessr | |
|---|---|---|
| How it gets the answer | Intercepts Google Maps API responses for exact coordinates | AI analyzes screenshots - reads signs, checks terrain, reasons about clues |
| Detection approach | Injects scripts into the page, monkey-patches XHR | CDP approach (external, no page injection) - significantly harder to detect |
| Behavior | Instant, robotic, perfect scores | Human-like camera panning, zooming, and map navigation |
| Accuracy | 100% (data extraction) | Variable (AI reasoning - makes mistakes like a human) |
Multi-Agent AI System - 4 specialist agents analyze each round in parallel, then a Synthesizer combines their findings into a final guess
Two Game Modes - Classic (untimed, full analysis) and Duels (1v1 competitive, timed with health tracking)
Two Play Styles - Aggressive (fully autonomous, AI does everything) or Assisted (AI coaching overlay, you place the guess)
Multiple AI Providers - Claude Code (subscription), Anthropic API, or OpenRouter (GPT-4o, Gemini, Grok, DeepSeek, and more)
Desktop App - Standalone Windows application with native window - no terminal needed
Web Dashboard - Real-time game status, manual controls, action log, and settings
Knowledge Base - 120+ instant-ID clues, 57 country-specific intel files, road numbering systems, vehicle databases, and language/script references
In-Game Overlay - Shows AI recommendations directly on screen during Assisted mode
Match Tracking - Duels health bars, round history, adaptive strategy tips, and post-match analytics
Dark & Light Theme - Full theme system across the entire dashboard
Browser Auto-Detection - Detects installed Chromium browsers (Chrome, Brave, Edge) and launches with CDP enabled
Human-Like Actions - Camera panning, zooming, map navigation, and pin placement mimic natural player behavior
- 🐍 Python 3.11+
- 📦 Node.js 18+
- 🌐 A Chromium browser (Chrome, Brave, or Edge)
# Install Python dependencies
pip install -r requirements.txt
python -m playwright install chromium
# Install dashboard dependencies
cd dashboard && npm install && npm run build && cd ..# Option A: One-command launch (opens browser + servers + dashboard)
start.bat # Windows
./start.sh # Mac/Linux
# Option B: Desktop app
python main.py
# Option C: Manual launch
brave.exe --remote-debugging-port=9222 --remote-allow-origins=*
python geo.py serve
python server.py
# Open http://127.0.0.1:8080📋 Using Claude Code (subscription mode)
- Select "Claude Code" in Settings
- Start a game in your browser
- Open a terminal in the AIguessr folder:
cd "C:\Users\YourName\Downloads\AIguessr" claude --dangerously-skip-permissions
- Tell Claude to play GeoGuessr
🔑 Using API mode (autonomous)
- Go to Settings and select Anthropic API or OpenRouter
- Enter your API key and select a model
- Start a game in your browser
- Click Auto Play - the bot plays autonomously
1. Connects to your browser via Chrome DevTools Protocol (external, no injection)
2. Captures Street View screenshots with human-like camera movements
3. 4 specialist agents analyze the scene in parallel:
├── Scout - driving side, landscape, climate, first impressions
├── Text Reader - signs, plates, phone numbers, scripts, storefronts
├── Meta Analyst - camera gen, Google car type, bollards, road markings
└── Terrain Analyst - vegetation, soil, architecture, natural features
4. Synthesizer combines findings + country intelligence → final lat/lng guess
5. Pin placed via React fiber traversal of GeoGuessr's embedded Google Maps
6. Human-like mouse movement submits the guess
AIguessr/
├── main.py # Desktop app entry point (pywebview)
├── geo.py # Browser controller (Playwright + CDP)
├── gc.py # TCP client for geo.py commands
├── brain.py # Multi-agent AI analysis system
├── server.py # FastAPI dashboard backend
├── config.py # Persistent app configuration
├── browser_detect.py # Chromium browser detection & launch
├── overlay.py # In-game coaching overlay injection
├── match_tracker.py # Duels match history & analytics (SQLite)
├── dashboard/ # React + Vite + Tailwind frontend
├── knowledge/ # GeoGuessr strategy knowledge base
│ ├── quick_identifiers.md # 120+ instant-ID clues
│ ├── meta_clues.md # Bollards, dishes, vegetation
│ ├── language_scripts.md # Scripts, stop signs, domains
│ ├── vehicle_clues.md # Google cars, plates, taxis
│ ├── road_numbering.md # Highway systems by country
│ └── countries/ # 57 per-country intel files
├── assets/ # Logo and icons
├── aiguessr.spec # PyInstaller build spec
├── build.bat # Build script (dashboard + PyInstaller)
├── installer.iss # Inno Setup installer script
├── .env.example # Environment variable template
├── requirements.txt # Python dependencies
├── start.bat # One-command launcher (Windows)
└── start.sh # One-command launcher (Mac/Linux)
| Provider | Models |
|---|---|
| 🟤 Anthropic | Claude Opus 4.6, Sonnet 4.6, Haiku 4.5 |
| 🟢 OpenAI (via OpenRouter) | GPT-4o, GPT-4o Mini, o3, o4-mini |
| 🔵 Google (via OpenRouter) | Gemini 2.5 Pro, Gemini 2.5 Flash |
| 🟣 Other (via OpenRouter) | Grok 3, DeepSeek R1 |
| ⚡ Claude Code | Any model via your subscription |
Will I get banned for using this?
Using any automation tool in GeoGuessr is against their Terms of Service and could result in a ban. AIguessr uses a CDP approach (external, no page injection) which is harder to detect than userscript-based tools, but no method is guaranteed undetectable. Use at your own risk.
How much does it cost to run?
- Claude Code: Uses your existing Claude Pro ($20/mo), Max ($100/mo), or Team subscription. No extra cost.
- Anthropic API: ~$0.01–$0.05 per round depending on the model.
- OpenRouter: Varies by model. Gemini Flash is the cheapest (
$0.005/round), Claude Sonnet is mid-range ($0.02/round).
Which browsers work?
Any Chromium-based browser: Google Chrome, Brave, or Microsoft Edge. Firefox and Safari are not supported because they don't support Chrome DevTools Protocol.
What game modes are supported?
- Classic - Full multi-agent analysis with all 4 specialists + Synthesizer. Best accuracy.
- Duels - Speed-optimized for 1v1 competitive matches. Tracks health bars and adapts strategy.
What's the difference between Aggressive and Assisted?
- Aggressive - Fully autonomous. The AI scans, analyzes, navigates the map, places the pin, and submits the guess with zero input from you.
- Assisted - The AI analyzes the scene and shows coaching hints via an in-game overlay (country, region, pin suggestion), but you make the final guess yourself.
Is my API key safe?
Yes. Your API key is stored locally in a .env file on your machine. It is never sent anywhere except directly to the AI provider you selected (Anthropic or OpenRouter). The key never leaves your computer otherwise.
How accurate is it?
Accuracy depends on the model used and the difficulty of the round. On average, it performs like a strong intermediate player - it excels at rounds with visible text, road signs, or distinctive landscapes, and struggles with coverage-less areas or ambiguous rural scenes. It is not a guaranteed 5000-point tool.
Can I use this on Mac/Linux?
The Python backend and dashboard work cross-platform. The desktop app (pywebview) works on Windows, macOS, and Linux. The .exe build and Inno Setup installer are Windows-only, but you can run directly with python main.py on any OS.
MIT - see LICENSE for details.