Getting Started
QualiLens runs entirely on your computer. Download the release, confirm the prerequisites below, and launch.
Platform support. macOS and Linux natively. On Windows, use WSL (Windows Subsystem for Linux). The launcher is a shell script (run.sh).
Check the requirements
QualiLens builds its own Python environment on first launch. The following must already be present.
| Requirement | Why | Check | Install |
|---|---|---|---|
| Python 3.11+ | Runs the backend and analysis pipelines | python3 --version | brew install python@3.12 or python.org |
| Node 18+ & npm (clone only) | Builds the interface once, on first launch. Not needed if you downloaded the release ZIP | node -v | nodejs.org |
| ffmpeg (optional) | Extracts audio from video; splits large recordings | ffmpeg -version | brew install ffmpeg |
You can skip ffmpeg if you only upload documents and audio files under about 24 MB. You will need it for video or large audio files.
Download QualiLens
Download the latest release, unzip it, and place the folder wherever you like. The release includes the pre-built interface — you need only Python, no Node or npm.
Download QualiLens.zipDevelopers who want to modify the code can clone the repository instead — this path requires Node 18+ to build the interface on first launch.
git clone https://github.com/iconerr/qualilens.gitCloud sync warning. If the folder sits inside a Dropbox, iCloud, or OneDrive directory, never run QualiLens on two computers against the same synced database simultaneously. Let the sync finish completely before opening the app on a second machine.
Launch QualiLens
Open a terminal in the QualiLens folder and run the launcher.
./run.shThe first run creates a Python environment, installs dependencies, and builds the interface — expect a minute or two. Every launch after the first is much faster. Once the server is up, it prints the address and opens your browser.
QualiLens running at http://127.0.0.1:8765 (Ctrl-C to stop)Stop the app with Ctrl-C in the terminal. Closing the browser tab does not stop it — runs continue in the background.
Add an API key
Open Settings from the top bar. Each provider gets its own card with Save, Test, and Remove controls. Paste your key, press Save, then Test to confirm it works.
You need a key from at least one of the four providers: Anthropic, OpenAI, Google, or Mistral. If you plan to upload audio or video, you also need an OpenAI key — transcription always runs through OpenAI's Whisper service regardless of which provider performs the analysis.
Where keys are stored. Keys live in the local SQLite database as plain text — not encrypted, not in a system keychain. Use Remove before sharing the folder or handing the computer to someone. Prefer a key scoped to this work, with its own spending limit.
Run your first analysis
Click New analysis. The wizard covers method selection, configuration, model choice, data upload, and cost estimation.
Start with a single short document — a typical first run costs a few cents and exposes every checkpoint before you commit a full corpus.
Accepted file types
Audio and video require an OpenAI key for transcription. Video also requires ffmpeg.
Updating QualiLens
Open Settings and find the Application card. Check for updates queries GitHub for the latest release (one request; nothing of yours is transmitted). When a newer release exists, Download and install applies it through a validated updater that replaces only application files — projects, keys, and uploads are structurally excluded.
After the update the app stops itself. Start it again with ./run.sh.