Oldcircle/geo-sleuth

What it solves

Finding where a photo was taken is normally hard when the photo has no text, sign, or landmark. geo-sleuth solves this by letting an AI agent use geometry and open geodata instead of visual recognition. It takes one photo and a sentence like "find where this photo was taken" and returns the camera position, the direction it was facing, and a satellite evidence image, with a confidence radius.

How it works

geo-sleuth is packaged as a standard Agent Skill: a SKILL.md file plus plain Python scripts. The agent reads SKILL.md, runs the scripts, and interprets results. The workflow is built around 20 single-purpose scripts that search and rank candidates. For example:

• It reads the photo for geometrical clues: pier spacing becomes a distance ruler, shadows become a bearing angle, ridge lines become fingerprints.
• It pulls data from OpenStreetMap (e.g., railway bridges, power lines, street trees) and elevation models.
• It scans regions, computes 360° horizons from elevation data at candidate points, and filters them.
• It fits the skyline from the photo against computed horizons, solves for camera roll, and overlays top candidates back onto the photo.
• Scripts rank candidates; the model (the agent) judges among the top few.
• It produces an evidence image with the camera position, field of view, and relevant features, plus a graded confidence.

It works with any agent that reads SKILL.md and runs shell commands: Claude Code, Codex, Cursor, Gemini CLI, OpenCode, GitHub Copilot, and others. The README demonstrates three case studies (rice paddy and viaduct, desert skyline, cherry tree street) showing accuracy to within 2 m, 100 m, and 3 m respectively.

Who it's for

Developers and researchers who want to give AI agents the ability to geolocate photos from environmental geometry. It is useful for digital forensics, historical photo analysis, travel documentation, or any application where a photo lacks GPS metadata but contains enough physical clues. It is also for people building agentic tools that need to run on multiple agent platforms.

Highlights

• One photo, one sentence: the interface is as simple as saying "find where this photo was taken" — no further engineering needed.
• Works without readable text: no license plates, signs, or landmarks required; geometry (pier spacing, shadows, ridge lines) carries the search.
• Geometry instead of guesswork: every clue is turned into a measurable constraint (distance ruler via pier spacing, bearing via shadows, fingerprint via ridge line).
• Scripts rank, the model judges: 20 single-purpose scripts search, score, and sort; the AI agent picks among the top few, improving reliability.
• Every claim points at a file: each conclusion names the command and output file, making the process transparent and verifiable.
• Cross-agent compatibility: a standard Agent Skill works across Claude Code, Codex, Cursor, Gemini CLI, OpenCode, GitHub Copilot, and others.
• Answers carry an error radius: coordinates plus/minus a radius, camera heading, evidence image, and graded confidence are returned.