Reverse Image Search

Find the source, similar images, or context for any image using reverse image search engines.

Setup

On first use, create a Python venv and install the dependency:

SKILL_DIR="$(dirname "SKILL.md")"
python3 -m venv "$SKILL_DIR/scripts/.venv"
"$SKILL_DIR/scripts/.venv/bin/pip" install -q PicImageSearch typing_extensions

typing_extensions is included here because the current PicImageSearch import path needs it on this machine's Python 3.14 runtime.

Usage

SKILL_DIR="$(dirname "SKILL.md")"
"$SKILL_DIR/scripts/.venv/bin/python3" "$SKILL_DIR/scripts/search.py" "<image_url_or_path>" [engine] [limit]

image_url_or_path: HTTP(S) URL or local file path
engine: yandex (default, most reliable), google (Google Lens path), bing, or all
limit: Max results per engine (default: 10)

Output is JSON with matched results including title, URL, thumbnail, and similarity when available.

If every selected engine fails due to upstream scraper breakage or anti-bot responses, the script exits non-zero so the caller can retry or fall back instead of treating the run as a clean success.

For Yandex hard failures, the error object includes attempt_log and diagnostics (including debug_html_path files in /tmp) so you can inspect exactly what response variant was received.

Engine Selection

yandex — Best overall: most stable, good at finding exact matches and similar images
google — Uses Google Lens via PicImageSearch; useful as a secondary source
bing — Useful as supplementary source
all — Run yandex first, then fall back to Google Lens and Bing only if Yandex is insufficient

Typical Workflow

User provides image (URL or file attachment)
Run search with yandex first
Only if yandex is insufficient, retry with all
Summarize findings: source, context, similar images

Do not start with all unless the user explicitly asks for all engines at once.