geo-sleuth

// Overview

geo-sleuth is an Agent Skill for photo geolocation: hand a coding agent a picture, say "find where this photo was taken", and it comes back with an estimated camera position with an error radius, the direction the camera was facing, a satellite evidence image and a graded confidence. It is a standard skill folder — `SKILL.md` plus plain Python scripts, reference notes and lookup data — so the same folder runs in Claude Code, Codex, Cursor, Gemini CLI, OpenCode, GitHub Copilot and any other agent that reads `SKILL.md` and can run shell commands.

The design splits the work into three layers. Scripts decide: a candidate board (`board.py`) tracks clues, likelihood ratios, exclusions and the next place to scan. Scripts perceive and rank: around twenty single-purpose tools handle EXIF, OCR, reverse image search, OpenStreetMap Overpass queries, sun and shadow geometry, elevation skylines, CLIP-scored satellite tiles and DINOv2 + SIFT street-view matching. The model only judges — reading clues from the frame, proposing hypotheses and picking among the few candidates the scripts have ranked. Every conclusion must cite a command that actually ran in the session and the file it produced.

That approach is aimed at photos with nothing to read. Instead of signs or landmarks, the skill turns geometry into evidence: evenly spaced bridge piers become a distance ruler, shadows become a bearing, and a mountain ridge line becomes a fingerprint matched against horizons rendered from elevation data. The README walks through three worked cases (a rice paddy with a railway viaduct, a desert skyline photographed with a slightly tilted phone, and a cherry-lined street in Vancouver) step by step, and reports per-script benchmarks; the project itself notes that its blind re-runs are regression checks on already-solved photos, not accuracy on unseen ones.

OpenStreetMap data is queried live rather than shipped, elevation comes from AWS Terrain Tiles, and the project asks that it only be run on your own photos or ones you have permission to analyse — never to find people who have not agreed to be found.

// What it does

• One-sentence interface: give the agent a photo and ask where it was taken; the skill returns coordinates with an error radius, camera heading, an evidence image and a graded confidence

• Skyline matching against elevation data: region scans along OSM features, ridge extraction from the photo, batch skyline scoring and a camera-roll solve in `terrain.py fit`
• OpenStreetMap Overpass tooling for feature co-occurrence, route corridors, line intersections and street-grid templates
• Image tooling: EXIF, OCR (Apple Vision on macOS, RapidOCR elsewhere), Baidu and Yandex reverse image search, CLIP-scored satellite tiles and DINOv2 + SIFT street-view ranking
• A script-driven candidate board that records clues, likelihood ratios and exclusions, so every claim points at a command and an output file
• One portable skill folder for Claude Code, Codex, Cursor, Gemini CLI, OpenCode and GitHub Copilot, with extensible per-country region packs

// Getting started

geo-sleuth needs Python 3.10+, uv, curl and an agent that can run shell commands; each script declares its own dependencies and uv installs them on first use. Reverse image search also needs Google Chrome or Playwright Chromium.

npx skills add Oldcircle/geo-sleuth

npx skills add Oldcircle/geo-sleuth -g -a claude-code -a codex -a cursor -a gemini-cli -a opencode -a github-copilot -y

git clone https://github.com/Oldcircle/geo-sleuth
mkdir -p ~/.agents/skills ~/.claude/skills
cp -r geo-sleuth/skills/geo-sleuth ~/.agents/skills/
ln -s ~/.agents/skills/geo-sleuth ~/.claude/skills/geo-sleuth

uvx playwright install chromium

uv run skills/geo-sleuth/scripts/doctor.py
uv run skills/geo-sleuth/scripts/doctor.py --network

find where this photo was taken

Commands and code are distilled from the project's own documentation — always check the official repo for the latest.