A little guidance.
A lot more finding.

Your first searchable folder.

Start with a small folder of screenshots or receipts. You can add more folders whenever you like.

1. Install Lenscribe.

   Choose the Windows, macOS, or Linux package on the downloads page. macOS has separate builds for Apple Silicon and Intel.

2. Choose a folder.

   Open Watched Folders, add a folder, and save. Lenscribe includes its subfolders. Use Folder Rules to exclude paths or limit which image sizes are indexed.

3. Connect a vision model.

   Open AI Extraction and choose a provider. Enter its API key if required, then use Fetch Models or enter an image-capable model ID manually.

4. Enable extraction.

   Turn on Automatic text extraction and save. Lenscribe processes pending images and watches for new ones. Overview shows your progress.

5. Find what you remember.

   Open Watched Folders → Inspect Files to search filenames and text, preview images, or edit a transcription. You can also search with your usual file tools.

Folders & files.

Lenscribe supports PNG, JPEG, and WebP. It watches your chosen folders and subfolders without moving your files into a new library. Symbolic links are not followed.

Exclude files you do not need.

Open Folder Rules → Exclude patterns. Add one pattern per line. Use / for folders, * for names, and ** for subfolders. A bare filename matches at any depth.

temp/**
*-thumbnail.png

Excluded files leave the index and processing queue. Their image files and existing text stay in place. Including them again imports any existing Lenscribe text.

Indexing and extraction have separate limits.

Maximum image size (MiB) in Folder Rules controls indexing; 0 includes every size. Automatic extraction and previews have a separate 20 MiB per image limit. A model may impose its own limits.

Pause, resume, or keep it in the background.

General contains pause/resume, start-at-login, and appearance settings. Pausing stops watching and extraction while keeping pending work. Resuming scans for changes. Use Quit Lenscribe in the tray menu to stop the app completely.

How the text stays with the image.

Lenscribe uses end-of-file (EOF) steganography: it stores extracted text after the original image data, leaving the visible image unchanged. It appends a small header, the raw UTF-8 transcription, and a checksummed footer without re-encoding the image. Processing the same file again replaces Lenscribe’s own trailer.

Readable with your usual tools.

The saved text is intentionally readable and unencrypted, so ordinary file tools can search it even when Lenscribe is not running. Copying or sharing the file carries its saved text too. This uses the appended-data approach to steganography (PDF).

PNG and WebP decoding are covered by the project’s tests; JPEG byte preservation is tested. See architecture and file format for the exact markers, validation, and write behavior.

Providers & vision models.

Choose your provider in AI Extraction. Use a model that accepts image input. A text-only model cannot transcribe your files.

Use a hosted provider.

Enter your API key, select a model with Fetch Models, and save. Hosted providers use their preset endpoints and may charge for API usage. A catalog entry marked unverified may not support images; use a known vision model or enter its exact ID manually.

Use a local model.

Run an image-capable model on your Ollama server, then select Ollama in Lenscribe. Its default base URL is http://localhost:11434. For an OpenAI-compatible server, use Custom / OpenAI Compatible; the default base URL is http://localhost:1234/v1.

Enter the base URL without the chat or generation endpoint. Supply an API key only if your server requires one. Processing stays on your machine when the model server runs there.

Search & read.

Find images in Lenscribe.

Open Watched Folders → Inspect Files and search the selected folder. Matches include filenames and extracted text. Current source builds also match word prefixes and common typos automatically. Check your release notes for feature availability.

Choose a result to preview the image, read or edit its text, retry an error, or reprocess it with your current model.

Search every file with your usual tools.

The text is readable even when Lenscribe is not running. Run these commands from the folder you want to search. They search every file in that folder and its subfolders.

grep -ar "coffee" .

-a treats image files as text; -r searches recursively. The . means the current folder.

Get-ChildItem -File -Recurse -Force |
  Select-String -Pattern "coffee" -Encoding utf8

Local search API.

Enable Search & Read → Local search API and save. The default address is http://127.0.0.1:47831. Port 0 chooses an available port; use the address shown in Lenscribe.

Search filenames and extracted text.

curl -G --data-urlencode "q=coffee" \
  --data-urlencode "limit=20" \
  "http://127.0.0.1:47831/search"

Read only the text.

Replace 1 below with a file ID returned by search.

curl "http://127.0.0.1:47831/files/1/text"

In Windows PowerShell, use curl.exe to call the curl executable explicitly.

Endpoints.

Search parameters.

q

Required search text.

folderId

Optional folder ID to limit the search to one indexed folder.

limit

Results per request. Defaults to 20, with a maximum of 100.

offset

Results to skip. Defaults to 0.

fuzzy

Defaults to true. Use false to search literal substrings without fuzzy matching.

/search returns a list of matches. /search/page also returns total, fuzzyApplied, and any search notice. Pagination and fuzzy parameters are described here for the current source; older releases may differ.

Data & privacy.

Local storage.

settings.json and index.sqlite live in Tauri’s application data directory. API keys are stored as plain text in settings.json. The database stores filenames, extracted text, cached results, and processing state.

A local Ollama or compatible endpoint can keep model processing on your computer. A hosted provider receives your images under its own terms. Lenscribe does not require environment variables for API keys.

Moving or editing processed images.

Moving or backing up a processed image keeps its text with it. Compatibility depends on your image viewer accepting trailing data. Re-saving or re-encoding an image in another application may remove the appended text.

See how the text stays with the image for the file layout, checksums, and compatibility details.

Troubleshooting.

Start with the error shown in Lenscribe. These checks cover the most common issues.

Find your logs.

lenscribe.log records startup, watching, extraction, retries, and API activity, even when the settings window is closed.

Logs exclude API keys, prompts, image payloads, extracted text, and raw model request/response bodies. Diagnostic file paths can appear. For a bug report, include your OS, Lenscribe version, reproduction steps, and sanitized log lines.

Build from source.

Lenscribe uses Tauri 2, Svelte/TypeScript, and a Rust core. Install the Bun version specified in package.json, stable Rust, and the platform dependencies listed in the development guide.

git clone https://github.com/ssubedir/lenscribe.git
cd lenscribe
bun install --frozen-lockfile
bun run tauri dev

To build the release executable without installers or signing updater artifacts, run bun run tauri build --no-bundle. The full development guide covers checks, the headless runner, logs, and releases.