Skip to content
NeksandPublic

About

Native, privacy-first AI screen overlay for desktop. A lightweight alternative to Cheating Daddy.

Resources

Contributing

Security policy

Stars

3 stars

Watchers

2 watching

Forks

Repository files navigation

TrueHalo

TrueHalo

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.

License Tauri 2 Rust Release Platform Size

Watch the demo · Features · Install · Comparison · Roadmap

Watch the demo

TrueHalo reading a code region and answering in the overlay

▶ 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.

What is TrueHalo?

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.

What's new in 0.4.4

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 audit and cargo audit now run on every push and pull request; both report no vulnerabilities.

What's new in 0.4.0

  • 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.

What's new in 0.3.1

  • 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.

What's new in 0.3.0

  • 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.

What's new in 0.2.3

  • Per-capture Image / Text choice — every screenshot keeps the compressed image and the recognized text; the toggle picks what gets sent.

What's new in 0.2.2

  • 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.

Why TrueHalo is small

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

Screenshots

TrueHalo main window with chat

AI providers & models Transparency & appearance
Settings — providers Settings — transparency

Settings — screen recording and privacy

Features

Ask about anything on screen

  • Two capture modes. Select a region (⌥⇧2 on macOS, Alt+Shift+2 on 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.

Chat that feels native

  • 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.

Built for a window that floats on top

  • 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 (NSWindowSharingNone on macOS, WDA_EXCLUDEFROMCAPTURE on 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.

TrueHalo vs Electron overlays

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 support

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.

Install

macOS (Apple Silicon)

You need: macOS 13 Ventura or newer on an M1/M2/M3/M4 Mac.

  1. Download TrueHalo-0.4.4-Installer.dmg from Releases.

  2. Open the DMG and drag TrueHalo into Applications.

  3. 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

    1. Open System Settings → Privacy & Security.
    2. Scroll down to Security and click Open Anyway next to TrueHalo.
    3. Confirm with Touch ID or your password, then click Open.

    macOS 13–14

    1. Right-click TrueHalo.app in Applications.
    2. 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
  4. 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.

Windows (x64)

You need: Windows 10 version 2004 (build 19041) or newer, or Windows 11. The installer downloads WebView2 automatically if it is missing.

  1. Download TrueHalo_0.4.4_x64-setup.exe from Releases.
  2. Run it. If SmartScreen says "Windows protected your PC", click More info → Run anyway — the installer is not signed with a commercial certificate.
  3. 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.

Linux (x64)

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.

  1. Download TrueHalo_0.4.4_amd64.deb or TrueHalo_0.4.4_amd64.AppImage from Releases.
  2. .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.
  3. API keys live in Secret Service (GNOME Keyring / KWallet unlocks it automatically). On systems without a keyring daemon, keys fall back to 0600 files under ~/.local/share/truehalo/credentials/.

The AppImage (~84 MB) bundles the system WebView; the .deb (~5.7 MB) uses the distro's.

First run (all platforms)

  1. Click the gear icon → AI Providers & Models.
  2. Paste an API key for a provider you already use: OpenRouter · Google AI Studio · OpenAI.
  3. Press Save. The key goes into the system credential store, not into a config file.
  4. Pick a model, close Settings, and press ⌥Space / Alt+Space to show the overlay.

Hotkeys

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

How it works

  1. You press a capture hotkey.
  2. TrueHalo hides its own window, takes one screenshot, and compresses it in memory.
  3. The image and your question are sent over HTTPS to the provider you picked.
  4. The answer streams back and is rendered as Markdown in the overlay.
  5. 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"]
Loading

Platform-specific code lives in small modules (overlay, capture, auth), so the UI and the streaming core are identical on both systems.

Privacy & security

  • 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.

Troubleshooting

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.

Roadmap

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.

Tech stack

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

Build from source

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 launch

You 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 nsis

The 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 dev runs an unsigned debug binary, so macOS cannot keep the Screen Recording permission for it. Test capture with the signed /Applications build.

Credits

License

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.

About

Native, privacy-first AI screen overlay for desktop. A lightweight alternative to Cheating Daddy.

Resources

Contributing

Security policy

Stars

3 stars

Watchers

2 watching

Forks

Releases

Packages

Contributors

Languages