Oldcircle/geo-sleuth

How to use it

Requires Python 3.10+, uv, and an agent that can run shell commands; each script declares its own dependencies and uv run installs them on first use. Install for all six agents user-wide:

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

Or by hand — one copy under ~/.agents/skills/ serves Codex, Cursor, Gemini CLI, OpenCode and GitHub Copilot; Claude Code reads a symlink:

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

Interface is one sentence to the agent: find where this photo was taken. Optional: Chrome for reverse image search (uvx playwright install chromium works), and export GEO_PROXY=socks5h://127.0.0.1:<port> routes every networked script through a proxy. No OSM data ships in the repo — scripts query it live, and you must credit © OpenStreetMap contributors when publishing query results.

How it works

The pipeline branches after a shared intake and board-building step, which is what makes a diagram worth drawing:

flowchart LR
  A[photo] --> B["intake.py<br/>EXIF · OCR · reverse search"]
  B --> C["board.py<br/>candidate board + ranking"]
  C --> D{which branch?}
  D --> E["sun/terrain/osm/pose<br/>shadows, skylines, corridors"]
  D --> F["sat_scan/match/gsv<br/>CLIP tiles, DINOv2+SIFT"]
  E --> G[board check + report]
  F --> G
  G --> H["evidence.py<br/>coords ± radius · confidence"]

The method was derived by breaking down 14 online-geolocation videos, 22 puzzles and real runs into rules; v2 moves every codifiable rule into board.py so rules get executed, not just read. Exclusions require read or computed evidence; observations and guesses can only lower a candidate's weight, not eliminate.

Limits

• Instructions and script output are in Chinese. The agent handles this and replies in your language, and it has solved cases outside China (a Los Angeles coastal road), but be aware of what you're reading.
• Slow. The showcased run took ~72 minutes end to end, roughly half spent waiting on computation.
• No published accuracy number yet. A public blind-test set with an end-to-end accuracy figure is on the roadmap, not delivered — the "±2 m" is a single showcased case, not a benchmark.
• Licensing is mixed. Code is MIT, but tables in data/ derived from Wikipedia are CC BY-SA 4.0, and live-queried OSM data is ODbL. The authors state a responsible-use restriction: run it only on your own photos or ones you have permission to analyze.