oldcircle/geo-sleuth

---

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.

The case: one photo, nothing to read

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

Installation

geo-sleuth is a standard Agent Skill: one folder holding SKILL.md, scripts/, references/ and data/. Install it with the skills CLI, or copy the folder yourself.

All six agents, user-wide, one command:

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

By hand:

git clone https://github.com/Oldcircle/geo-sleuth
mkdir -p ~/.agents/skills ~/.claude/skills
cp -r geo-sleuth/skills/geo-sleuth ~/.agents/skills/              # Codex, Cursor, Gemini CLI, OpenCode, GitHub Copilot
ln -s ~/.agents/skills/geo-sleuth ~/.claude/skills/geo-sleuth     # Claude Code

~/.agents/skills/ is read by Codex, Cursor, Gemini CLI, OpenCode and GitHub Copilot, so one copy there covers all five. Each agent’s own folders, from its docs:

Any other agent that reads SKILL.md and runs shell commands works the same way: put the folder where it looks for skills.

How it works

The work is split into three layers. Scripts decide, scripts perceive and rank, the model only judges among the top few.

flowchart LR
  A["photo"] --> B["intake.pyEXIF · OCR · reverse image search"]
  B --> C["board.pycandidate board: clues, likelihood ratios, ranking, next step"]
  C --> D{"which branch?"}
  D --> E["sun.py · terrain.py · osm.py · pose.pyshadows, skylines, OSM corridors, camera pose"]
  D --> F["sat_scan.py · match.py · gsv.py · baidu_pano.pyCLIP-ranked satellite tiles, DINOv2+SIFT street view"]
  E --> G["board.py check · report"]
  F --> G
  G --> H["evidence.pycoordinates ± radius · evidence image · graded confidence"]

Every conclusion has to point at a command that actually ran in the session and the file it produced. Exclusions need read or computed evidence; observations and guesses can only lower a candidate’s weight.

Toolbox

Twenty scripts, one job each. The full table with data sources is in skills/geo-sleuth/references/data-sources.md.

The three steps from the case above (region scan, batch skyline scoring, camera position from pier spacing) are built into the skill as subcommands: terrain.py scan / ridge / fit, imgprep.py piers, geo.py spacing. Case scripts tuned to that photo are kept in examples/rail-skyline-session/ for reference.

Benchmarks

Per-operator measurements:

The method comes from breaking down 14 videos by online-geolocation creators, 22 puzzles and a set of real runs, then turning what works into rules and scripts. v2 moves every rule that can be code into board.py, so the rules get executed, not just read.

Requirements and setup

You need Python 3.10+, uv, curl, and an agent that can run shell commands. Each script declares its own dependencies; use uv run, which installs them on first use. Keep the complete skill folder, including data/ and the helper modules in scripts/.

Reverse image search requires Google Chrome or Playwright Chromium. The scripts try Chrome first and automatically fall back to Chromium. If neither is installed:

uvx playwright install chromium

Linux may also need browser system libraries: uvx playwright install --with-deps chromium. See the Playwright browser setup guide. After a Playwright upgrade, rerun the installer if it reports a missing browser executable.

From a clone of this repository, run these commands (also work in PowerShell):

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

For an installed skill, use its actual scripts/doctor.py path, or ask your agent to run it. The local check tests Python, uv, curl, bundled lookup tables, a writable working directory and an actual browser launch. --network also probes the services without uploading photos. --json produces machine-readable diagnostics. Exit code 1 means a failed check; warnings identify optional features that may not work. uv may fetch Playwright on the first run; doctor does not load OCR or ML models. Passing an endpoint probe does not guarantee image uploads, model downloads, imagery coverage or freedom from CAPTCHAs.

To check the local processing pipeline on your own image before using online search:

uv run skills/geo-sleuth/scripts/intake.py photo.jpg --out-dir intake --no-rev

Open intake/intake.md, then inspect the listed crops and OCR output. This checks metadata, image preparation and OCR; it does not perform reverse image search. Omit --no-rev for the full intake. On macOS OCR prefers Apple Vision; other systems use RapidOCR, also available as a fallback. match.py and sat_scan.py install ML packages and download model weights on first use; allow extra time and disk space. uv and model downloads still need network access even when a particular processing step works locally.

Troubleshooting

Language: maintained instructions, CLI help, errors, generated report headings and default evidence labels are in English. Source text (OCR, place names, search responses and screenshots) is preserved rather than rewritten; the agent explains it and writes the final report in your language. The last version with Chinese instructions is frozen at the zh-final tag and is no longer updated.

Roadmap

• [ ] Operator-level test on synthetic terrain cases for terrain.py scan / fit
• [ ] Google Lens as a third reverse-search engine
• [ ] CI on Linux and Windows
• [ ] A public blind-test set of unseen photos with an end-to-end accuracy number

Contributing

Issues and pull requests are welcome, see CONTRIBUTING.md. The most useful contributions are a transferable clue for references/clues/ (with a source), a new data source with its licence, or a run on your own photo where the skill went wrong and why.

Star History

Acknowledgements

• OpenStreetMap contributors (ODbL). No OSM data ships in this repository; the scripts query it live. Credit © OpenStreetMap contributors when you publish query results.
• AWS Terrain Tiles (Terrarium elevation).
• modood/Administrative-divisions-of-China.
• DINOv2 (Meta AI), CLIP (OpenAI).
• Sources and licences for the lookup tables are in skills/geo-sleuth/data/README.md.

License

MIT, see LICENSE. Tables in data/ derived from Wikipedia are CC BY-SA 4.0; see skills/geo-sleuth/data/README.md.

Responsible use: run it on your own photos or ones you have permission to analyze, never to find people who have not agreed to be found.