lens

Image-library indexing and search

1,100/1,100 images · 98 s · $2.21 · search ~2 s

crates.io · lens-cli 0.1.2 (binary: lens)

Ask for a photo the way you’d ask a person. lens captions every image in a folder once with a fast vision model, stores the captions in one plain JSONL file, and answers any natural-language query by putting the whole index into a single model call. No vector database, no embeddings, no daemon — the index is a file; search is a request.

no vector database
no embeddings
no daemon

1,100/1,100 images
98 s
$2.21
search ~2 s

How lens works, in two moves

index — once

your photos

any folder, thousands of images

lens index

captions every photo once — 25 parallel workers on Cerebras gemma-4-31b

index.jsonl

one plain text file — no vector database, no daemon

same file, read again on every search — index once, ask as many times as you like

find — any time, ~2 s

lens find "campfire at night"

describe the photo the way you'd ask a person

one model call

whole index in a single request — chunked and reranked for bigger libraries

your photo

matched and returned in seconds

Install

Homebrew

brew install treygoff24/tap/lens

Shell installer — prebuilt binary, no toolchain needed

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/treygoff24/lens/releases/latest/download/lens-cli-installer.sh | sh

Cargo — requires Rust 1.85+

cargo install lens-cli

Configure

Set the key, run the doctor, done.

CEREBRAS_API_KEY required: vision captioning + search — get one at cloud.cerebras.ai

verify your setup

lens doctor --online --json

How it works

Indexing walks the directory deterministically, skips unchanged files via a freshness key, and fans captions across 25 concurrent workers on Cerebras gemma-4-31b.
Every model call passes a budget-reservation gate first, so parallel workers can’t collectively overshoot --max-dollars.
Search serializes the whole index into one model call (chunked with a rerank pass for bigger libraries) and returns matching images in seconds.
Indexing is crash-safe and resumable: results append as they land, so a killed run continues exactly where it stopped.

Pairs well with

scoutsiblings — one indexes photos, the other code and documents receiptssame envelope contract and exit-code dictionary, by design

Known limits

Windows untested and unsupported in v1; HEIC decode fallback is macOS-only.
Whole-index-in-one-prompt has an economic ceiling around 30K+ images — a v2 seam, documented, not hidden.