# LocalLens

> Local-first file chat. Point it at any folder — notes, code, research — and it builds a private brain you can chat with. Every answer comes with citations, and nothing leaves your machine.

LocalLens is an open-source reference implementation of retrieval-augmented generation (RAG) that runs entirely on a user's hardware. It is built with [Bun](https://bun.sh), TypeScript, and the [QVAC SDK](https://docs.qvac.tether.io) from Tether. The complete pipeline — file discovery, chunking, embedding, retrieval, prompt assembly, and completion — lives in eight TypeScript files in `src/`, small enough to read in an afternoon and complete enough to ship.

This page is the markdown alternate of the LocalLens documentation homepage at [https://docs-locallens.vercel.app](https://docs-locallens.vercel.app).

## What LocalLens gives you

- **Local RAG over any folder.** Walks any directory, filters by safe extensions, ignores caches, chunks files, embeds them, and retrieves grounded context — all on-device.
- **On-device chat.** QWEN3 1.7B (Q4 quantized) for chat. A 600M fallback model exists for slimmer hardware. No GPU required.
- **Cited answers.** Every answer carries bracketed citations linking back to the exact source chunk and file path.
- **Plain JSON storage.** Brains and chunks persist to `.locallens/store.json`. Inspect with `cat`, ship in a backup, diff in git.
- **CLI and browser entry points.** Same core. Prove the pipeline in a terminal first, then host it on `Bun.serve` for a real UI.
- **No cloud dependencies.** No OpenAI key, no Pinecone account, no Anthropic key, no API tokens, no telemetry.

## What you need

- Bun `>=1.3.0`
- Node `>=22.17.0`
- A machine that can run a 1.7B-parameter quantized model. A 600M fallback exists for slimmer hardware.

## Where to start

- [Overview](https://docs-locallens.vercel.app/en/docs/overview) — the product, the user flow, and what local AI buys you.
- [Architecture](https://docs-locallens.vercel.app/en/docs/architecture) — the retrieval and completion pipeline, end to end.
- [Setup](https://docs-locallens.vercel.app/en/docs/setup) — install, run the CLI, run the browser app, verify the build.
- [Walkthrough](https://docs-locallens.vercel.app/en/docs/walkthrough) — module by module, from domain types out to the UI.
- [Structure](https://docs-locallens.vercel.app/en/docs/structure) — the responsibility split, the request trace, and what each file should not own.
- [Extend](https://docs-locallens.vercel.app/en/docs/extend) — PDF parsing, voice questions, and richer diagnostics.

## Why local-first matters

Cloud RAG services hold three things that should stay yours: the documents you chunk, the queries you make, and the model's responses. Each of those is a leak surface. Local-first inverts the trade: you accept a smaller model and a single-user setup in exchange for *nothing leaves the machine*. For personal knowledge bases, regulated environments, and air-gapped research, that trade is the right one.

LocalLens shows the trade can be made without losing the basics — citations, multi-file retrieval, two ways to run it — in eight files of legible TypeScript.

## Comparison to alternative approaches

| | LocalLens | Cloud RAG (Pinecone + OpenAI) | Self-hosted vector DB |
|---|---|---|---|
| Data leaves machine | No | Yes | Configurable |
| API keys | None | Required | Optional |
| GPU required | No | No | Often |
| Reference code size | 8 files | Glue code over services | Larger |
| Production scale | Single-user | Multi-tenant | Multi-tenant |
| Cost at idle | Zero | Per-call + storage | Hosting |
| Cited answers | Yes | Depends on stack | Depends on stack |

LocalLens is the right tool for *learning, prototyping, and single-user private brains*. It is not the right tool for production-scale shared retrieval.

## License and source

- License: MIT
- Repository: [github.com/souzavinny/locallens](https://github.com/souzavinny/locallens)
- Docs repository: [github.com/souzavinny/locallens-docs](https://github.com/souzavinny/locallens-docs)
- Issues: [github.com/souzavinny/locallens/issues](https://github.com/souzavinny/locallens/issues)

## Machine-readable endpoints

- llms.txt: [/llms.txt](https://docs-locallens.vercel.app/llms.txt)
- OpenAPI: [/openapi.json](https://docs-locallens.vercel.app/openapi.json)
- Sitemap: [/sitemap.xml](https://docs-locallens.vercel.app/sitemap.xml)
- A2A agent card: [/.well-known/agent-card.json](https://docs-locallens.vercel.app/.well-known/agent-card.json)
- API catalog (RFC 9727): [/.well-known/api-catalog](https://docs-locallens.vercel.app/.well-known/api-catalog)