A native AI overlay that answers questions about what is on your screen.
For people working with documents, code, and translations: press a hotkey, grab a region, and get
a fast answer in a floating window — in any app, on macOS, Windows, and Linux.
Watch the demo · Features · Install · Comparison · Roadmap
▶ Watch the 37-second launch film (1080p, with sound)
Not a cheating tool. TrueHalo is a lightweight productivity overlay for people who work with documents, code, and translations and need a fast answer about what's on screen. It answers only what you explicitly ask about, one screenshot at a time. The window-exclusion feature exists for privacy — the same reason API keys stay in the system credential store and the app never sends telemetry.
TrueHalo must not be used to misrepresent your work — not in exams, interviews, hiring screens, or any proctored assessment. The project does not support, condone, or facilitate cheating.
TrueHalo is a small desktop app for people who work with documents, code, and translations. When you need a fast answer about something on screen — an error, a paragraph to translate, a piece of code, a form — you press one hotkey, drag a box around it, and ask a question. The answer appears in a translucent window that stays on top.
It is not a background recorder or an always-listening assistant:
- You start every request. No timers, no continuous capture, no microphone.
- You choose the model. Bring an API key from OpenRouter, Google Gemini or OpenAI — or run models locally with Ollama.
- Your keys stay in the OS. They live in the system credential store and never reach the UI layer.
Typical uses: reading dense documentation, debugging code, translating an error message or a paragraph, or summarising a long page you are allowed to look at.
Current release: 0.4.4 (Releases).
- SQLite advisory fixed — rusqlite 0.42 / libsqlite3-sys 0.40 closes RUSTSEC-2026-0459 / CVE-2026-119375.
- Dependency refresh — Tauri 2.12.7, Vite 8.3.8, react-markdown 10.1, plus current base64, ashpd and security-framework releases. No functional changes.
- Supply-chain audits in CI — production
npm auditandcargo auditnow run on every push and pull request; both report no vulnerabilities.
- Token budget — a live estimate under the message box and automatic oldest-first trimming of long threads. System instructions and your newest message always survive.
- Clear positioning — TrueHalo is for documents, code, and translations; hard no to cheating use.
- Ephemeral history that means it — chats are wiped the moment the app quits, not on the next start.
- Send guards — no requests without a model selected, and over-limit profiles stay blocked until Unlimited is on or files are trimmed.
- Assistant profiles — instructions plus attached files sent with every request; pick one in the chat header.
- Local models — Ollama, LM Studio or any OpenAI-compatible server. No key needed.
- Click-through mode, history controls (text-only history, ephemeral mode), deeper stealth, version in Settings.
- Per-capture Image / Text choice — every screenshot keeps the compressed image and the recognized text; the toggle picks what gets sent.
- First-run setup wizard — pick a provider, paste the key, choose a model, send a test request.
- Customizable hotkeys — toggle / region / fullscreen can be re-recorded in Settings; conflicts roll back.
- History and export — search, rename, Markdown and JSON export; everything stays in local SQLite.
- Local OCR text mode — on-device text recognition (macOS Vision, Windows OCR) with an editable preview before sending; falls back to the image when no text is found.
- Quick Actions — one-click prompts (Explain, Summarize, Translate, Fix code, Extract text, What's wrong?) plus your own custom actions stored locally.
- Cost dashboard — a Usage tab with today/all-time token counts, estimated cost from the provider catalogs ("—" when a price is unknown), per-model rows and a 7-day chart.
Most AI overlays are Electron apps: they ship a whole Chromium browser (200+ MB) just to draw one window. TrueHalo is written in Rust and uses the WebView that your operating system already has.
Installer size Typical Electron overlay 200+ MB TrueHalo 9 MB
| Typical Electron overlay | TrueHalo | |
|---|---|---|
| Download | 200+ MB | 6.8 MB DMG · 3.8 MB EXE |
| Installed app | 300–500 MB | ~9 MB |
| Runtime | bundled Chromium | the system WebView |
| Idle memory | hundreds of MB | a fraction of that |
| Cold start | seconds | almost instant |
| AI providers & models | Transparency & appearance |
|---|---|
![]() |
![]() |
- Two capture modes. Select a region (
⌥⇧2on macOS,Alt+Shift+2on Windows) or grab the whole screen (⌥⇧3/Alt+Shift+3). Shortcuts can be re-recorded in Settings → Shortcuts. - Works over any app. The overlay floats above your work and can be moved by its header.
- Images are compressed locally before they are sent, so uploads stay small (a Retina screenshot usually drops from 10–20 MB to under 1 MB).
- Local OCR text mode. Settings → Screenshot input offers Auto / Text only / Image only. Text is recognized on-device, shown in an editable preview, and only the text is sent — cheaper and faster than an image. If no text is found, the screenshot is sent instead.
- Setup wizard — first launch walks through provider → API key → model → test request.
- Streaming answers — text appears as the model writes it; stop it any time with
Esc. - Four providers, one UI — OpenRouter, Google Gemini, OpenAI and local servers, with a live model list.
- Assistant profiles — instructions plus attached files sent with every request while a profile is selected.
- Vision models — screenshots are sent as images to models such as Claude, Gemini and GPT-4o. Text-only models are blocked before the request with a clear message.
- Quick Actions — one-click prompts with a system instruction each; add your own actions, stored locally.
- Token counter and cost — see usage per message, per session and in the Usage tab; old screenshots are replaced with a short placeholder so you do not pay for the same image twice.
- History — conversations persist in local SQLite; search, rename, export to Markdown or JSON.
- Real transparency — the opacity slider (5–100 %) changes the actual window alpha.
- Optional frosted glass on top of the transparency, for readability.
- Invisible to screen recorders — OBS, Zoom and QuickTime do not see the overlay at all
(
NSWindowSharingNoneon macOS,WDA_EXCLUDEFROMCAPTUREon Windows 10 2004+). On Windows the overlay turns fully opaque while protection is on, so the recorded area shows the desktop instead of a black box; transparency and glass return when you switch protection off. - Tray mode — hide TrueHalo from the Dock or taskbar and control it from the menu bar / tray.
- Remembers its place — position, size and settings are stored locally in SQLite.
- No telemetry, no accounts, no analytics.
Most AI overlays ship a whole Chromium browser just to draw one window. TrueHalo uses the WebView your operating system already has, sends nothing in the background, and keeps your keys in the OS credential store.
| Typical Electron overlay | TrueHalo | |
|---|---|---|
| Runtime | bundled Chromium | Tauri 2 (Rust + system WebView) |
| Download | 200+ MB | 6.8 MB DMG · 3.8 MB EXE |
| Installed app | 300–500 MB | ~9 MB |
| Capture | often continuous or session-based | on demand, one hotkey at a time |
| Audio capture | usually bundled | not included, by design |
| API key storage | config files | system credential store, never in the UI |
| Telemetry | varies | none |
| License | varies | GPL-3.0 |
| Platform | Status | Installer |
|---|---|---|
| macOS 13 Ventura or newer · Apple Silicon | ✅ Available | TrueHalo-0.4.4-Installer.dmg |
| Windows 10 2004+ / Windows 11 · x64 | ✅ Available | TrueHalo_0.4.4_x64-setup.exe |
| Ubuntu 22.04+ / Debian 12+ · x64 | ✅ Available | TrueHalo_0.4.4_amd64.deb or TrueHalo_0.4.4_amd64.AppImage |
The React UI and the Rust core are shared. The macOS backend uses AppKit and the Keychain; the Windows backend uses Win32 (DWM acrylic, display affinity) and the Credential Manager; the Linux backend uses the Desktop Portal for capture and Secret Service (with a locked-down file fallback) for keys.
Linux notes: capture goes through xdg-desktop-portal (present on GNOME/KDE out of the box; on
minimal window managers install xdg-desktop-portal plus a backend). Global shortcuts need X11 or a
compositor that forwards them; the tray icon and capture buttons always work. Screen-recording
exclusion has no Linux equivalent, so that switch stays off. Arch users: a
truehalo-bin AUR package is in progress
(packaging/aur); until it lands, use the .deb or AppImage from Releases.
You need: macOS 13 Ventura or newer on an M1/M2/M3/M4 Mac.
-
Download
TrueHalo-0.4.4-Installer.dmgfrom Releases. -
Open the DMG and drag TrueHalo into Applications.
-
Launch it. macOS will say it cannot verify the app — this is normal, because the build is signed with a local certificate instead of a paid Apple Developer ID.
macOS 15 or newer
- Open System Settings → Privacy & Security.
- Scroll down to Security and click Open Anyway next to TrueHalo.
- Confirm with Touch ID or your password, then click Open.
macOS 13–14
- Right-click TrueHalo.app in Applications.
- Choose Open, then Open again in the dialog.
Prefer Terminal? This removes the quarantine flag without dialogs:
xattr -dr com.apple.quarantine /Applications/TrueHalo.app
-
When macOS asks for Screen Recording, allow it and restart the app: System Settings → Privacy & Security → Screen & System Audio Recording → TrueHalo. This permission is what lets the hotkeys capture the screen. It is used only after you press a hotkey.
You need: Windows 10 version 2004 (build 19041) or newer, or Windows 11. The installer downloads WebView2 automatically if it is missing.
- Download
TrueHalo_0.4.4_x64-setup.exefrom Releases. - Run it. If SmartScreen says "Windows protected your PC", click More info → Run anyway — the installer is not signed with a commercial certificate.
- Launch TrueHalo from the Start menu or the tray icon. Windows has no screen-recording permission, so there is nothing else to approve.
Screen-recording exclusion needs Windows 10 2004+. On older builds TrueHalo keeps the switch off instead of drawing a black rectangle in recordings.
You need: Ubuntu 22.04+ or Debian 12+ (or any distro with WebKitGTK 4.1 and an appindicator
library), plus xdg-desktop-portal running in the session for screenshots.
- Download
TrueHalo_0.4.4_amd64.deborTrueHalo_0.4.4_amd64.AppImagefrom Releases. .deb:sudo apt install ./TrueHalo_0.4.4_amd64.deb, then launch TrueHalo from the app menu. AppImage:chmod +x TrueHalo_0.4.4_amd64.AppImage && ./TrueHalo_0.4.4_amd64.AppImage.- API keys live in Secret Service (GNOME Keyring / KWallet unlocks it automatically). On systems
without a keyring daemon, keys fall back to
0600files under~/.local/share/truehalo/credentials/.
The AppImage (~84 MB) bundles the system WebView; the .deb (~5.7 MB) uses the distro's.
- Click the gear icon → AI Providers & Models.
- Paste an API key for a provider you already use: OpenRouter · Google AI Studio · OpenAI.
- Press Save. The key goes into the system credential store, not into a config file.
- Pick a model, close Settings, and press
⌥Space/Alt+Spaceto show the overlay.
| macOS | Windows | Action |
|---|---|---|
⌥Space |
Alt+Space |
Show / hide the overlay |
⌥⇧2 |
Alt+Shift+2 |
Capture a selected region |
⌥⇧3 |
Alt+Shift+3 |
Capture the full screen |
Esc |
Esc |
Stop the answer / hide the overlay |
↵ |
Enter |
Send |
⇧↵ |
Shift+Enter |
New line |
- You press a capture hotkey.
- TrueHalo hides its own window, takes one screenshot, and compresses it in memory.
- The image and your question are sent over HTTPS to the provider you picked.
- The answer streams back and is rendered as Markdown in the overlay.
- The temporary screenshot file is deleted immediately.
flowchart LR
A["Hotkey<br/>⌥⇧2 / Alt+Shift+2"] --> B["Hide the overlay"]
B --> C["Capture one frame"]
C --> D["Compress in Rust<br/>(no disk left behind)"]
D --> E["Send to your provider<br/>over HTTPS"]
E --> F["Stream the answer"]
F --> G["Render Markdown<br/>in the overlay"]
Platform-specific code lives in small modules (overlay, capture, auth), so the UI and the
streaming core are identical on both systems.
- API keys are stored in the system credential store (Keychain on macOS, Credential Manager on Windows). The React UI can ask the backend to start a request, but it never receives the key.
- No background capture. A screenshot is taken only after you press a hotkey, and the temporary file is deleted right after it is read.
- No telemetry. The only network requests are the ones to the AI provider you selected.
- Overlay protection uses the OS feature for hiding windows from screen capture. Your chats stay private even if you share your screen.
- Local data: chats and settings are in a local SQLite database. Nothing is synced anywhere.
| Problem | Fix |
|---|---|
| macOS: "TrueHalo is damaged and can't be opened" | xattr -dr com.apple.quarantine /Applications/TrueHalo.app, then open again |
| macOS: no Open Anyway button | Launch the app once, then reopen Privacy & Security; or use the Terminal command above |
| macOS asks for Screen Recording again after an update | System Settings → Privacy & Security → toggle TrueHalo off and on → restart the app |
| macOS asks for a password when opening Settings | Settings → Screen Recording & Privacy → Fix (choose Always Allow once). Since 0.2.2 the model list is cached, so a normal start no longer reads the keychain |
| Settings or the window shows an error instead of content | Details are written to ~/Library/Logs/TrueHalo/truehalo.log (frontend error: …); paste that line into an issue |
| Windows: "Windows protected your PC" | SmartScreen → More info → Run anyway |
| Windows: a black box appears where the overlay was | Keep Hide the window from other screen recordings on — the overlay then stays fully opaque. Older builds (< Windows 10 2004) cannot exclude a window at all, so the switch stays off |
| Windows: a DRM-protected video captures as black | Protected video surfaces cannot be captured by any screen recorder |
| Hotkeys do nothing | Another app already owns the shortcut — close it or change the shortcut in your system settings |
| The model list is empty | The provider rejected the key (401/429). Check the key and your quota |
Logs on macOS: ~/Library/Logs/TrueHalo/truehalo.log.
Shipped:
- macOS and Windows builds
- Four providers with a live model catalog (OpenRouter, Gemini, OpenAI, local)
- Region / full-screen capture with local compression
- System credential storage and capture exclusion
- First-run setup wizard
- Customizable global shortcuts with conflict rollback
- History: search, rename, Markdown/JSON export
- Local OCR text mode with editable preview and image fallback
- Built-in and custom Quick Actions
- Usage tab with token counts, estimated cost and a 7-day chart
- Assistant profiles with context injection (instructions + files)
- Click-through mode
- Local models via Ollama / OpenAI-compatible servers
- Token budget with oldest-first trimming and a live estimate
Next, in order of expected impact:
- Major performance optimization — further reduce CPU and RAM use while capturing and while streaming.
- Code signing for both platforms (Apple Developer ID, Authenticode), then a signed auto-updater.
- Local OCR on Linux (Tesseract backend) to match macOS and Windows.
| Layer | Technology |
|---|---|
| Shell | Tauri 2 |
| Backend | Rust, Tokio, reqwest, rusqlite |
| Frontend | React 18, TypeScript, Vite, Tailwind CSS |
| Capture | macOS screencapture · Windows PowerShell + WinForms |
| Credentials | macOS Keychain · Windows Credential Manager |
| Window | AppKit on macOS · Win32 / DWM on Windows |
macOS:
git clone https://github.com/Neksand/TrueHalo.git
cd TrueHalo
npm install
# One-time: create a stable local signing identity, so macOS keeps the
# Screen Recording permission across rebuilds.
npm run sign:setup
npm run app:install # build, sign, install to /Applications and launchYou need Xcode Command Line Tools (xcode-select --install), Node.js 18+ and Rust stable.
Windows (PowerShell; install the Rust MSVC toolchain and Visual Studio Build Tools first):
git clone https://github.com/Neksand/TrueHalo.git
cd TrueHalo
npm install
npm run tauri build -- --bundles nsisThe installer appears in src-tauri/target/release/bundle/nsis/.
Development:
npm run tauri dev # hot reload
npm run build # type-check the frontend
cargo test --manifest-path src-tauri/Cargo.toml
npm run tauri devruns an unsigned debug binary, so macOS cannot keep the Screen Recording permission for it. Test capture with the signed/Applicationsbuild.
- Built with Tauri, React and Tailwind CSS.
Misuse for cheating in exams, interviews, or proctored assessments is against the purpose of this project. See the notice at the top of this README.
GPL-3.0 © TrueHalo contributors.
TrueHalo is free software: you can redistribute it and/or modify it under the terms of the GNU General
Public License as published by the Free Software Foundation, either version 3 of the License, or (at
your option) any later version. See the LICENSE file in this repository.



