<div align="center">

🧭 geo-sleuth

An agent skill that finds where a photo was taken — and shows its work.

<p align="center"> <a href="README.md"><img alt="English" src="https://img.shields.io/badge/English-1f6feb?style=flat-square"></a> <a href="README.zh-CN.md"><img alt="Simplified Chinese" src="https://img.shields.io/badge/%E7%AE%80%E4%BD%93%E4%B8%AD%E6%96%87-dbeafe?style=flat-square"></a> </p> <p align="center"> <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-yellow.svg"></a> <a href="https://www.python.org/downloads/"><img alt="Python 3.10+" src="https://img.shields.io/badge/python-3.10%2B-blue.svg"></a> <a href="https://agentskills.io"><img alt="Agent Skill: SKILL.md" src="https://img.shields.io/badge/Agent%20Skill-SKILL.md-8A2BE2.svg"></a> <a href="CONTRIBUTING.md"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg"></a> <a href="https://github.com/Oldcircle/geo-sleuth/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/Oldcircle/geo-sleuth?style=social"></a> </p> <p align="center"> <b>Works with</b><br> <a href="https://code.claude.com/docs/en/skills"><img alt="Claude Code" src="https://img.shields.io/badge/Claude%20Code-D97757?style=for-the-badge&logo=claude&logoColor=white"></a> <a href="https://developers.openai.com/codex/skills"><img alt="Codex" src="https://img.shields.io/badge/Codex-000000?style=for-the-badge"></a> <a href="https://cursor.com/docs/skills"><img alt="Cursor" src="https://img.shields.io/badge/Cursor-000000?style=for-the-badge&logo=cursor&logoColor=white"></a> <a href="https://geminicli.com/docs/cli/skills/"><img alt="Gemini CLI" src="https://img.shields.io/badge/Gemini%20CLI-1A73E8?style=for-the-badge&logo=googlegemini&logoColor=white"></a> <a href="https://opencode.ai/docs/skills/"><img alt="OpenCode" src="https://img.shields.io/badge/OpenCode-211E1E?style=for-the-badge&logo=opencode&logoColor=white"></a> <a href="https://docs.github.com/en/copilot/concepts/agents/about-agent-skills"><img alt="GitHub Copilot" src="https://img.shields.io/badge/GitHub%20Copilot-000000?style=for-the-badge&logo=githubcopilot&logoColor=white"></a> <br>_{…and any other agent that reads <code>SKILL.md</code> and runs shell commands.} </p> <img src="docs/hero.gif" width="880" alt="From one photo to a camera position: the photo, the region scan, the skyline overlays, the evidence image">

No text. No plates. No landmarks. One bridge, one mountain. Located to within 2 m.

</div>

---

Quick start

npx skills add Oldcircle/geo-sleuth

Pick your agents when prompted. Then hand your agent a photo and say:

find where this 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 (see Requirements and setup). That is the whole interface. The agent reads SKILL.md, runs the scripts, and comes back with the camera position, the direction it was facing and a satellite evidence image. Prefer to copy the folder yourself? See Installation.

Why geo-sleuth

• One photo, one sentence. Give your agent a photo and say find where this photo was taken. You get back the camera position, the direction it was facing, and a satellite evidence image.
• It works when there is nothing to read. No sign, no plate, no landmark: OpenStreetMap geometry, elevation data, satellite tiles and street view carry the search on their own.
• Geometry instead of guesswork. Pier spacing becomes a distance ruler, shadows become a bearing, a ridge line becomes a fingerprint that elevation data can be matched against.
• Every claim points at a file. A conclusion has to name the command that ran in the session and the file it produced. Population and fame are not evidence.
• Scripts rank, the model judges. Twenty single-purpose scripts search, score and sort; the model only picks among the top few.
• One skill, every agent. A standard Agent Skill — SKILL.md plus plain Python scripts — so the same folder runs in Claude Code, Codex, Cursor, Gemini CLI, OpenCode and GitHub Copilot.
• Answers carry an error radius. Coordinates ± radius, the camera heading, an evidence image and a graded confidence.

Cases

None of these photos had GPS data. Each case lists what the skill read from the photo, how it narrowed the search, and how far the result landed from the confirmed camera position.

Each case is a record of one run by one model. The skill tells the agent how to work; what to query, how to filter and how many top results to check are the model's own decisions, so a different model or different decisions may not reach the same result. Under each case, Reproduction conditions and checkpoints lists the input, the hint, the key parameters and what each stage should still cover, so you can find the step where your own run diverged.

<table> <tr> <td width="33%" align="center"><a href="#1-a-rice-paddy-and-a-viaduct"><img src="docs/case/thumb.jpg" alt="An oven at the edge of a rice paddy, a viaduct and a mountain behind"></a></td> <td width="33%" align="center"><a href="#2-a-desert-skyline-one-degree-off"><img src="docs/cases/desert/thumb.jpg" alt="A sand dune ridge and a range of bare dark mountains"></a></td> <td width="33%" align="center"><a href="#3-a-cherry-tree-on-a-vancouver-street"><img src="docs/cases/cherry/thumb.jpg" alt="A flowering cherry tree over a sidewalk"></a></td> </tr> <tr> <td><b>1 · Rice paddy and viaduct</b><br>_{Railway bridges × skyline × pier count.}</td> <td><b>2 · Desert skyline</b><br>_{Power lines × skyline × a phone tilted by 1°.}</td> <td><b>3 · Cherry street</b><br>_{Street-tree open data × shadows × street view.}</td> </tr> <tr> <td align="center"><b>±2 m</b><br>_{Qingyuan, Guangdong}</td> <td align="center"><b>within 100 m</b><br>_{Da Qaidam, Qinghai}</td> <td align="center"><b>3 m</b><br>_{Vancouver, Canada}</td> </tr> </table>

1. A rice paddy and a viaduct

A phone photo with the EXIF stripped: a white oven at the edge of a harvested rice paddy, a long viaduct in the distance, a steep mountain on the right. Not a single character in the frame. One message to an agent with this skill installed, and it came back with the camera position and the direction the camera was facing.

photo → 27,335 → 171 → 14,372 → 22 → 3 → 1 → ±2 m

| Step | What it did | Candidates left | |---|---|---| | Read the photo | Poles on the viaduct are catenary masts, so it is an electrified railway. Pier spacing used as a ruler (32 m span assumed): the left segment is about 0.5 km away, the right one over 1 km. A steep mountain about 3 km away. Rice harvested but grass still green, so no frost yet. | South China, as a bet, not a proof | | Region scan | Pulled every railway bridge in the region from OpenStreetMap: 27,335 segments. Sampled a point every 400 m and computed the 360° horizon from elevation data at each one. Kept points with flat ground nearby, a clear mountain within a few km, and a flat horizon next to it. | 171 sites | | Skyline fit | Placed candidate camera positions around each site and rendered the ridge line seen from each one: 14,372 positions. The top 20 were within 0.1° of each other, so it added a constraint: the bridge must be near on the left and far on the right. | 22 | | Overlay check | Drew the top three ridge lines back onto the photo. Score #1 (Fuzhou) had a bump hidden behind the oven, which is why it scored well. #3 (Huizhou) sloped where the photo is flat. #2 (Qingyuan) fit from the foot of the mountain to the edge of the frame. | 1 | | Pier count | 17 piers in the photo become 17 bearings from the camera. Where they hit the railway line, the intersections must be evenly spaced. Combined with the skyline: first a band about 300 m long, then a single spot. | ±2 m |

<div align="center"> <img src="docs/case/02-pier-ruler.jpg" width="820" alt="17 piers marked on the viaduct, spacing used as a ruler"><br> _{Piers as a ruler: wide spacing on the left means near, tight spacing on the right means far.}<br><br> <img src="docs/case/04-skyline-top3.jpg" width="520" alt="Top three skyline overlays: Fuzhou, Qingyuan, Huizhou"> <img src="docs/case/06-evidence.jpg" width="292" alt="Evidence image: camera position, field of view, the railway and the mountain"><br> _{Left: the top three ridge lines drawn onto the photo. Right: the evidence image the skill produced.} </div> <details> <summary>More figures from this run</summary> <br> <img src="docs/case/03-region-scan.jpg" width="720" alt="Region scan: railway bridges in grey, candidate sites in orange"><br> _{Region scan: every railway bridge in the region (grey), sites that pass the horizon test (orange).}<br><br> <img src="docs/case/05-pier-rays.jpg" width="720" alt="Bearings to 17 piers intersecting the railway line"><br> _{Pier count: bearings to the 17 piers intersect the line; only one camera position makes the spacing even.}<br><br> _{The run took about 72 minutes end to end, roughly half of it waiting on computation.} </details> <details> <summary>Reproduction conditions and checkpoints</summary> <br>

• What this record is: the table is the first time this method solved the photo (Claude Opus 5.0), not a blind re-run; its steps were later written into the skill.
• Input: a 1280×1707 phone photo with EXIF stripped. The images in this README are display versions and are not suitable as input.
• Candidates: all 27,335 OSM railway-bridge segments in the region, excluding only those tagged electrified=no (as rail_mtn_scan.py did then and terrain.py scan does by default now), with no highspeed filter. Catenary masts only show that the line is electrified; the correct line, the Guangzhou–Qingyuan intercity, has 55 bridge segments in OSM and none is tagged highspeed=yes.
• Checkpoints: the 171 sites that pass the horizon test should include intercity bridge segments near the answer; the skyline fit covers 14,372 camera positions, the top 20 lie within 0.1°, and "bridge near on the left, far on the right" cuts them to 22; the top three are overlaid; the 17 pier bearings fix the point.
• Case scripts: examples/rail-skyline-session/ holds the scripts tuned to this photo. OSM splits one line into many ways with the same name; joint.py tries every same-name way near the candidate center in turn, so the result does not depend on the order the query returns them.

</details>

2. A desert skyline, one degree off

A sand dune in the foreground, a range of bare dark mountains behind it, and a few pylons at the foot of the range. There is no text, road or building in the frame, and reverse image search returned only generic desert photos from northwest China.

<div align="center"><img src="docs/cases/desert/00-photo.jpg" width="820" alt="The photo: a sand dune ridge, bare dark mountains, pylons at the foot of the range"></div>

photo → 1,537 sites → stuck around 10 px → solve a 1° tilt → 1 site → one dune

| Step | What it did | Left | |---|---|---| | Read the photo | The pylons are the only man-made objects, so the camera is within a few kilometres of a power line. Sand, gravel and bare rock point to northwest China. | 4 provinces | | Power lines × terrain | osm.py geom pulled every power line in Xinjiang, Gansu, Ningxia and Qinghai. terrain.py scan worked along them with elevation data and kept the places where mountains fill the view. | 1,537 sites | | Skyline fit | terrain.py ridge traced the ridge in the photo, and terrain.py fit compared it with the ridge seen from each site. In Qinghai the top 25 sites all scored between 9.6 and 11.7 px; the true site was 9th. | stuck | | The tilt | A phone held 1° off leve