geo-sleuth

Overview

geo-sleuth is an Agent Skill for photo geolocation. It uses OpenStreetMap geometry, elevation skylines, satellite imagery and street view, and can solve photos with no text, plates or landmarks. It returns coordinates with an error radius, camera heading, an evidence image and graded confidence, with every conclusion tied to a command and file produced in the session.

Key Features

• One photo and a short request return the camera position, facing direction, satellite evidence image and graded confidence.
• Uses OpenStreetMap geometry, elevation skylines, satellite tiles and street view, so it can work without readable signs, plates or landmarks.
• Twenty-odd single-purpose scripts search, score and rank candidates; the model judges only among the top few.
• Every conclusion must point to a command that ran in the session and the file it produced.
• Answers carry coordinates with an error radius, camera heading, evidence image and confidence grade.
• A standard SKILL.md plus Python scripts package works across Claude Code, Codex, Cursor, Gemini CLI, OpenCode and GitHub Copilot.

Use Cases

• Geolocate a phone photo whose EXIF data has been stripped and whose frame contains no text.
• Narrow a search with OSM railway or power-line features and elevation-based skyline matching.
• Check candidate locations against satellite imagery and historical street view.
• Produce an evidence image showing the inferred camera position, field of view and nearby features.

Getting Started

• Install with npx skills add Oldcircle/geo-sleuth, selecting the agents when prompted.
• Give the installed agent a photo and ask it to find where the photo was taken.
• On first use, ask the agent to run doctor.py from the installed skill's scripts folder and address any failed checks.
• Alternatively, clone the repository and copy the skill folder into the agent's skills directory.

Deployment & Requirements

• Python 3.10+, uv, curl, and an agent that can run shell commands.
• Keep the complete skill folder, including data and helper modules in scripts.
• Reverse image search requires Google Chrome or Playwright Chromium; the scripts fall back from Chrome to Chromium.
• match.py and sat_scan.py use CUDA when supported, then MPS, then CPU, and print the selected device.
• On Windows, the default uv run install uses a CPU-only torch; an NVIDIA GPU requires a CUDA build supported by the driver.

Before You Adopt

• License: MIT. Review its terms before using, modifying, or distributing the project.
• Reverse image search depends on an installed Chrome or Chromium browser.
• Case results reflect one model's decisions, so another model or different decisions may not reproduce them.
• Published blind re-runs are regression checks on previously solved photos, not measurements on unseen photos.
• Some runs can spend substantial time waiting on computation.