Fzi
fzi — fuzzy image search — finds local images by describing them on the command line.
Stack: Python (stdlib only; numpy optional). Private repo.
fzi recursively scans an image tree, embeds every image into a vector space shared with text (via an OpenAI-compatible embedding router), and ranks by cosine similarity to your query. Vectors are cached locally in a TSV under a hard 2 GiB LRU budget — least-recently-used images are evicted first.
Interactive browser
Bare fzi in a terminal opens a full-screen fzf-style collage.
- Opens instantly, indexes async — the browser appears immediately, embeddings run in a background thread pool. Progress saved to cache incrementally; quitting mid-index keeps everything embedded so far.
- Cache bar — live
cache ▰▱… N%against the 2 GiB LRU budget. - Live resolving — type and results re-rank as you go (query re-embedded on a short debounce; ranking over cached vectors is instant).
- Query status dot — coloured indicator: grey (idle), amber (typing / debouncing), amber circle (embedding), green (settled).
Commands
fzi "sunset over water" # one-shot text search
fzi -r ~/Pictures/Phone "tacos" -n 10 # scope + limit
fzi "a red car" -p # inline thumbnail previews
fzi "a red car" --open # open results in image viewer
fzi image vacation.jpg -p # reverse image-to-image search
fzi index ~/Pictures # pre-build the cache
fzi stats # cache size / budget / mode
fzi doctor # endpoint + cache health check