LocalLens is an open-source, local-first file chat. Point it at any folder and it builds a private brain you can chat with. Every answer comes with citations and nothing leaves your machine. It is built with Bun, TypeScript, and the QVAC SDK.

Does LocalLens send my files to the cloud?

No. QVAC runs the chat and embedding models locally. File discovery, chunking, retrieval, and completion all happen in-process on the user's machine. No document, query, or response is sent to a third-party service.

What hardware do I need to run LocalLens?

Any machine that can load a 1.7B-parameter quantized language model. A 600M fallback is wired in for slimmer hardware. No GPU is required. The runtime needs Bun >= 1.3.0 and Node >= 22.17.0.

QVAC is Tether's on-device AI SDK. It exposes a small surface for loading quantized models, running completions, computing embeddings, and chunking and indexing text for retrieval-augmented generation. LocalLens uses QVAC for both the chat and the embedding pipeline.

How is LocalLens different from cloud RAG services?

Cloud RAG services hold the documents you chunk, the queries you make, and the model's responses — each is a leak surface. LocalLens runs the entire pipeline on your machine, so nothing leaves. The trade is a smaller model and a single-user setup. The whole reference implementation is eight TypeScript files in src/.

Is LocalLens production-ready?

LocalLens is a reference implementation, intended for learning, prototyping, and single-user private brains. It is not a multi-tenant production vector database. For large corpora or shared retrieval, use a dedicated vector database alongside the patterns the LocalLens docs describe.

What languages does the documentation support?

English (canonical), Spanish, Portuguese, and Japanese. Switch locales via the language selector in the navigation bar or by visiting /es/, /pt/, /ja/ directly.

Where can I report a bug or contribute?

Open an issue or pull request at github.com/souzavinny/locallens for the application, or github.com/souzavinny/locallens-docs for this documentation. Both repositories are MIT-licensed.

A local-first file chat, without the cloud

LocalLens turns any folder into a private brain. Ask questions, get cited answers — all on your machine. Built with Bun, TypeScript, and the QVAC SDK.

Quick Start Read the Walkthrough

bun run cli examples/sample-brain "your question"

Sample brain

12 files · indexed locally

ready

Ask this brain about its local files

The whole loop, in eight TypeScript files

File discovery, chunking, retrieval, prompting, completion, persistence, and two entry points. Small enough to teach, complete enough to extend.

File discovery

Walks any folder, filters by safe extensions, ignores caches and lockdirs, normalizes paths for the browser file picker.

Local RAG

QVAC ragChunk + ragIngest + ragSearch produce grounded retrieval — no cloud vector database, no API keys.

On-device inference

QWEN3 1.7B (Q4) for chat, GTE-Large FP16 for embeddings. Ships with a 600M fallback for slimmer machines.

Cited answers

Every answer carries bracketed citations linking back to the exact source chunk in the original file.

Plain JSON store

Brains and chunks persist to .locallens/store.json. Inspect them with cat, ship them in a backup, diff them in git.

CLI + Browser

Two entry points over the same core. Prove the pipeline in a terminal, then host it on Bun.serve for a real UI.

Local AI by design

Files never leave the machine

QVAC runs models locally. Ingestion and search happen in process — no document is uploaded anywhere.

Answers stay grounded

The prompt builder forces the model to cite retrieved chunks or admit it doesn't know. No hallucinated paths.

Cloud-optional

Drop the network and LocalLens still works. Add a tunnel later if you want to share a brain with a teammate.

Small enough to read

Eight TypeScript files in src/ split by responsibility. Read the whole codebase in an afternoon.

See the architecture →

Built with Bun, TypeScript, and QVAC · MIT License