Geo Sleuth Photo Locator
Infer a photo’s camera position from terrain, map and imagery clues, with evidence you can inspect.
- Source repo
- Oldcircle/geo-sleuth
- Stars
- ★ 1.7k
- Last updated
- today
- License
- MIT
- Primary language
- Python
- FA score
- 71/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code
- Cost
- Free, no paid service needed
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- An investigator needs to narrow down a photo with no GPS, readable text or obvious landmark using a railway bridge, skyline and terrain.
- Not a fit if
- Users who need fully offline geolocation
- Teams requiring an accuracy benchmark on unseen photos
- Source review
- 71/100 · Some gaps
What does this agent do, and when should you use it?
Geo Sleuth is an Agent Skill made of `SKILL.md` and Python scripts, installable in Codex, Claude Code, Cursor, Gemini CLI, OpenCode, GitHub Copilot, or another agent that can run shell commands. After the agent reads clues from a photo, `board.py` tracks candidate places, evidence scores and the next scan; focused scripts analyze terrain, OpenStreetMap, satellite imagery and street views. Scripts retrieve and rank candidates first, while the model judges among the top results. The final report includes coordinates with an error radius, camera heading, graded confidence and a satellite evidence image. It runs locally with Python 3.10+ and `uv`, while several map, imagery and search steps require network services; the README’s example cases are regression checks, not an accuracy measure on unseen photos.
Give a photo to an agent with the skill installed and ask it to locate where the photo was taken. intake.py reads EXIF, creates crops, runs OCR and can search Baidu and Yandex for reverse image matches; clues.py looks up clue tables, and board.py records candidates, clues, likelihood scores, exclusions and scan order. The agent then chooses tools as needed: osm.py queries OpenStreetMap features, terrain.py scans terrain and fits ridgelines, sun.py analyzes shadows, sat_scan.py scores satellite tile candidates, and gsv.py, baidu_pano.py and match.py inspect street-view panoramas. geo.py and pose.py calculate bearings, distances and camera pose; evidence.py produces a satellite image marked with the camera view. The agent returns a position, error radius, heading and confidence, with each conclusion tied to a command actually run and its output file.
- An investigator needs to narrow down a photo with no GPS, readable text or obvious landmark using a railway bridge, skyline and terrain.
- A geography enthusiast wants to shortlist and verify a possible location from dunes, mountains and the placement of power lines.
- An urban researcher can combine public street-tree data, shadows, slope and street view to locate a street photograph.
- A Codex or Claude Code user wants an auditable photo-location workflow in an agent, including an evidence image and an error radius.
- A maintainer wants to check whether a script change improves known cases by rerunning the documented desert, railway or cherry-street examples.
How do you install or deploy this agent?
Install Python 3.10+, uv and curl; Google Chrome or Playwright Chromium is needed for reverse image search. Install the skill with the skills CLI and choose agents when prompted:
npx skills add Oldcircle/geo-sleuthFor a user-wide install to all six documented agents:
npx skills add Oldcircle/geo-sleuth -g -a claude-code -a codex -a cursor -a gemini-cli -a opencode -a github-copilot -yOr clone the repository and copy the skill folder:
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-sleuthOn Linux, install Chromium system libraries if needed:
uvx playwright install --with-deps chromiumHow do you use this agent?
After installation, give the agent a photo and ask it to locate where it was taken. On first use, run scripts/doctor.py from the installed skill folder and address failed checks:
uv run /path/to/geo-sleuth/scripts/doctor.pyTo check local metadata, image preparation and OCR without reverse image search:
uv run /path/to/geo-sleuth/scripts/intake.py photo.jpg --out-dir intake --no-revInspect intake/intake.md, the listed crops and OCR output. For a full location search, ask the agent “find where this photo was taken”; it will run the relevant scans and checks, then return a position, heading and evidence image. To probe network services, run doctor.py --network; this probes endpoints without uploading photos. Dependencies and models may download on first use; match.py and sat_scan.py download model weights when first run.
What are this agent's strengths and limitations?
- One standard
SKILL.mdand Python scripts work with six named agents and, according to the README, other agents that can read the file and run shell commands. board.pymakes candidate tracking, scoring, exclusions and scan order part of the workflow; the README requires conclusions to point to an actual command and output file.- The toolbox spans OpenStreetMap, elevation, satellite tiles and street view, allowing geometry and skyline analysis when a photo has no text or landmark.
- Results include an error radius, camera heading, confidence grade and evidence image; example blind reruns report distance error and elapsed time.
- Setup needs Python 3.10+,
uv,curland a browser; first use may download dependencies, Playwright or machine-learning models. - Reverse search, map queries, satellite imagery and street view depend on external services and network access, and may encounter 403/429 responses, CAPTCHAs, timeouts or limited coverage.
- The README says its blind-test photos were previously solved and are regression checks; there is no public end-to-end accuracy figure for unseen photos.
- Maintained instructions, CLI help, errors and default evidence labels are in English; source text in other languages is preserved.
How does this agent compare with similar options?
The README contrasts its method with guessing from population or a location’s fame: Geo Sleuth ranks candidates with scripts and ties conclusions to commands and output files. It also uses Baidu and Yandex reverse image search, but provides no direct performance comparison with other geolocation products.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Geo Sleuth Photo Locator This agent | 71 · Some gaps | Agent plugin / skillFree | ★ 1.7k | today | Python | Codex · Claude Code |
| BambooAI Data Analyst | 85 · Good | Web appFree + model costs | ★ 793 | 2d ago | Python | OpenAI API · Claude API |
| MiroFlow Research Agent | 53 · Major gaps | CLIFree + model costs | ★ 3.1k | 8mo ago | Python | — |
| DecisionBox | 44 · Major gaps | Self-hosted serviceFree + model costs | ★ 120 | 1d ago | Go | OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
The README describes the photo workflow, scripts, data-source categories, network searches, and evidence files, making data flows highly transparent (3). Scripts are divided by task and the supplied material shows no obviously excessive permissions (least privilege 2), but it does not establish per-request confirmation for network access or uploads (user confirmation 1). Retention, deletion, and third-party handling of photos and EXIF data are not adequately described (sensitive data 1). The docs and tests show optional proxying, network probes, and external map services, but give limited detail on the scope and mitigation of external effects (2). Environment checks are documented, but the supplied material does not establish a thorough dependency security review (1). MIT licensing and data-source information are present, though item-level attribution rules are not clear (source attribution 2); no recovery or rollback procedure is shown (1).
The README, tool descriptions, and test files present a broadly coherent candidate-ranking, evidence-recording, and reporting workflow, but static evidence cannot establish that every claim matches implementation (self-consistency 2). Python, uv, browser setup, doctor checks, and tests for network mirror fallback support ordinary dependency availability (2). Some service failures are distinguished or reported, but the evidence does not establish user-facing recovery guidance for all failure cases (failure messages 2).
The docs cover photo geolocation, scenes without text clues, multiple detailed cases, and several Agent platforms (audience and scenarios 3). Region packs, offline regression tests, and explicit unsupported states are shown, but the supplied material does not fully enumerate out-of-scope cases or accuracy boundaries (capability boundaries 2). The trigger phrase is simple and the docs explain that the Agent reads SKILL.md and runs commands; no anti-misfire guidance is shown (trigger precision 2). Installation paths, Python requirements, platform differences, and macOS versus other OCR options are documented (environment fit 3).
The README has clear quick-start, installation, architecture, toolbox, cases, and benchmark sections (information architecture 3). It provides CLI and manual installation, platform paths, and a first-use doctor step (install notes 3). Script and skill names are generally clear, but no compatibility or naming stability policy is shown (2). Cases, command examples, benchmarks, and setup instructions are extensive (examples and FAQ 3). The README labels blind runs as regression checks rather than accuracy on unseen photos and reports run times, but other limitations are not fully covered (known limitations 2). The MIT license text is complete (3). No release history or changelog appears in the supplied material (versioning and changelog 1). A contribution link and PR invitation exist, but ownership, maintenance commitments, and update path are unclear (maintenance responsibility 1).
The stated output includes coordinates with an error radius, heading, evidence image, and graded confidence; conclusions are expected to point to commands and output files (output usability 3). Combining OSM, terrain, satellite, and street-view methods offers substantial added capability for photos without GPS (marginal value 3). The README reports runs of roughly 32–72 minutes, indicating substantial time and computation costs, with no general resource budget provided (cost benefit 1).
The README requires claims to reference session commands and produced files, and shows steps, candidate counts, and visual evidence (claim traceability 3). The supplied tests cover offline logic and runtime boundaries, and the README reports benchmarks, but this material does not independently verify the case geolocation outcomes (cross-source corroboration 2). The docs label some judgments as assumptions or bets and distinguish regression checks from accuracy on unseen photos (fact-inference separation 3).
- Photos and EXIF data may be processed by OCR, reverse-image-search, mapping, or street-view services; the supplied material does not fully explain each service's retention and privacy handling.
- Documented runs can take tens of minutes. The blind runs use previously solved cases and are explicitly described as regression checks, not accuracy measurements on unseen photos.
FAQ
Do I need an API key or paid subscription?
Are photos uploaded to online services?
intake.py --no-rev for a local pipeline check and says doctor.py --network probes services without uploading photos.Can I use it for fully offline geolocation?
intake.py --no-rev.