Getting Started

What FlowLens is

FlowLens is a desktop voice overlay for macOS and Windows. It runs in the background, opens from a global shortcut, captures the current screen only when invoked, records a short spoken request, and answers in a compact overlay.

The app is useful when the context is already visible:

• a weak prompt in an editor
• a stack trace or failed terminal command
• a rough PR description, issue, or technical note

Supported platforms

Linux is intentionally out of scope because screen capture, global shortcuts, packaging, and permission recovery would widen the platform surface before the core interaction is mature.

Install the Electron app

FlowLens is meant to feel like a normal desktop utility, not a project the user has to rebuild. The packaged app installs once, starts from the OS shell, keeps running in the tray/menu bar, and opens setup or the overlay from the global hotkey.

After installation, a non-technical user should not need npm install, npm run build, npm start, or a terminal restart loop. They launch FlowLens like any other app, complete setup once, and then use the hotkey or tray/menu-bar controls.

First-run setup

The intended non-technical path is now in-app:

1. Install FlowLens from a packaged build.
2. Launch the app.
3. Complete the setup window.
4. Choose a provider preset or configure an OpenAI-compatible endpoint.
5. Add the provider key, base URL, model, and protocol if needed.
6. Add the ElevenLabs key.
7. Pick an ElevenLabs voice and TTS model.
8. Choose a microphone.
9. Grant microphone and screen permissions.
10. Confirm the global hotkey.
11. Decide whether FlowLens should launch at login.

If setup is incomplete, the global hotkey opens setup instead of invoking the overlay. This prevents the most confusing failure mode: pressing the shortcut before keys, permissions, or model settings are valid.

Daily use

Once setup is complete:

1. Press the configured hotkey.
2. Speak the request while the Matrix visualizer reacts to microphone input.
3. Wait for the response card.
4. Read the markdown answer, hear the short spoken summary if enabled, and copy the final output.
5. Use the tray/menu-bar menu for settings, launch-at-login, update checks, overlay reset, and quit.

The app stays alive in the background after windows close. Closing setup or the overlay does not require rebuilding or rerunning a command.

Build a local package

Until a signed public release is published, maintainers and reviewers can build the Electron package locally from the FlowLens desktop app repository:

npm install
npm run dist:win -- --publish never

or on macOS:

npm install
npm run dist:mac -- --publish never

Build output is written to the release/ folder. For a faster unpacked development package on Windows:

npm run package

Developer mode

Developer mode is still available, but it is not the intended end-user path:

npm install
npm run build
npm start

For active app development with the renderer dev server and watched main-process build:

npm run dev

First launch checklist

1. Complete setup or open settings from the tray/menu bar.
2. Confirm the OpenAI-compatible provider key, base URL, protocol, and model.
3. Confirm the ElevenLabs API key, voice, and TTS model.
4. Grant microphone access.
5. Grant screen recording or screen capture access.
6. Test the global shortcut on a screen with visible context.
7. Use the tray/menu-bar item to open settings, check updates, reset overlay position, or quit.

Config and secret storage

At runtime, FlowLens stores non-secret config in Electron userData:

The app migrates the legacy ~/.flowlens/config.json file into userData when needed. API keys are migrated into the secret store and removed from the JSON config.

Run this docs site

From the Fumadocs project:

npm install
npm run dev

Then open http://localhost:3000/docs.

This docs site uses Next.js, Fumadocs UI, Fumadocs MDX, local content in content/docs, generated collections from source.config.ts, and LLM-readable routes from the Fumadocs source loader.