Desktop App

The capsule

The capsule is a small floating bar that sits at the bottom center of your screen. It only appears when a supported AI app is open (Claude Desktop, ChatGPT, Codex, Cursor, or VS Code).

Idle state

When no file has been dropped, the capsule is idle. It shows rotating "Token Tax" education copy and does nothing. Clicking it while idle is a no-op. The capsule hides when you switch to a non-AI app and reappears when you return.

Dropping a file — Scenario A (question first)

This is the primary flow and produces the best results.

1. Type your question in the AI chat box. "Which California customers spent over $10K?" — the question is sitting in the chat, not sent yet.
2. Drag your file from Finder onto the capsule. The moment the file lands: - Omna reads your question from the chat box via macOS Accessibility API - Computes a content fingerprint of the file - Checks if the file is already indexed
3. Omna slices the file (Tier 1 if indexed, Tier 2 if not — see How Slicing Works)
4. The sliced file is attached to the chat. Omna writes the file URL to your clipboard and simulates ⌘V in the AI chat. An attachment chip appears: "customers-slice.csv · 261 rows · 49K tokens".
5. The result card appears showing savings. Auto-dismisses after 10 seconds.
6. Hit Send — your question and the sliced file go to the AI.

Dropping a file — Scenario B (file first)

If you drop a file before typing your question:

1. The capsule enters Pending state — it shows the file name and waits.
2. Type your question in the AI chat box.
3. Press the Ready button on the capsule — Omna reads your question at that moment and begins slicing.

Pending state stays active indefinitely — you can take your time writing the question.

Result card

After every successful slice, a result card appears showing:

• Scenario: Killed / Crushed / Redirected / All rows matched (see How Slicing Works)
• Token reduction: how many tokens were cut (e.g., "−77% tokens")
• Without Omna vs. With Omna cost comparison
• Row counts: how many rows were sent vs. total in the file

The card auto-dismisses after 10 seconds. You can close it with the × button.

The background indexer

The indexer runs continuously in the background, building a search index of every file in your watched folders. Pre-indexed files use the fast Tier-1 path: sub-second on small files, and about 20 seconds on a 4-million-row parquet the first time you query it after Omna starts (then sub-second for every later query on the same file). The indexer is what makes that fast path possible — see How Slicing Works and USER_JOURNEY §5 Step 8.

What it builds

For each supported file, the indexer writes a small set of artifacts into the file's own subfolder under ~/Library/Application Support/Omna/index/:

• **index.bm25** — keyword index storing each row's term frequencies for fast exact matching
• **index.embed** — 384-number semantic fingerprint for each row, enabling meaning-based search
• **index.hnsw.segs** — segmented Hierarchical Navigable Small World (HNSW) graph built once over the embeddings so Tier-1 queries jump directly to nearby vectors instead of scanning every row
• **index.rows** — memory-mapped random-access row-text store so Tier-1 reads only the rows that survived the threshold, not the whole file
• **index.fingerprint** — content hash that drives change detection (so Omna never re-indexes a file whose bytes haven't changed)

The default disk cap is 20 GB across all subfolders. When the cap is hit, Omna evicts the least-recently-queried file's whole subfolder.

When it runs

The indexer is always running in the background but pauses automatically when:

• You're on battery (resumes when plugged in)
• System CPU is above 70%
• You're on a Zoom, Meet, or Teams call (detected via microphone active state)

By default the indexer caps itself at half your Mac's cores (Low-power mode: 30%) and schedules itself at a low macOS QoS, which steers it toward the efficiency cores. The combination keeps foreground apps snappy and avoids thermal throttling on fanless MacBooks.

How it handles large files

A 4-million-row parquet file takes several hours to fully index overnight. During that time:

• Rows already indexed are available for Tier 1 search
• Rows not yet indexed fall through to Tier 2 (live embedding on drop)
• Progress is shown in the menu bar: "NYC Taxi indexing… 2.1M / 3.95M rows · 53%"

If Omna is quit mid-indexing, it resumes where it left off — it doesn't restart from row 1.

Adding and removing folders

Open the menu bar → Add files or folders… (⌘O). A Finder picker appears — select any file or folder. Omna adds it to the watch list and starts indexing immediately.

To remove a folder: menu bar → Preferences… (⌘,) → remove the folder. Omna stops watching it and deletes its index artifacts.

The menu bar

Click the O icon in your Mac menu bar to see:

1.2M token tax intercepted
~$3.60 on API · ~240 extra prompts
47 files sliced · 4m ago
─────────────────────────
Index: 12 / 45 · indexing
  Desktop      5 / 5    ✓ done
  Documents    4 / 15   indexing…
  Downloads    3 / 25   queued
Add files or folders…           ⌘O
⏸ Pause indexing               ⌘.
─────────────────────────
🛡 PII Masking: ON
🐢 Low-power mode: OFF
☑ Launch at login
─────────────────────────
Preferences…                   ⌘,
Open log
Reveal data folder
─────────────────────────
Quit Omna                       ⌘Q

Key settings

PII Masking toggle: When ON, Omna replaces personal information with placeholders before the sliced data reaches the AI. When OFF, raw data is sent. Default: ON.

Low-power mode: When ON, Omna uses fewer CPU cores for indexing — useful when you're on a Zoom call or doing a heavy compile. Takes effect on next launch. Default: OFF.

Launch at login: Omna starts automatically when you log in. Recommended: ON.

Onboarding (first launch)

The first time you open a supported AI app after installing Omna, a card appears asking for Accessibility permission. This is a one-time setup — Omna needs it to read your typed question from the AI chat box.

After granting permission, the card dismisses automatically and the capsule appears. The onboarding card never reappears, even if you reinstall.

Quitting and uninstalling

Quit: Menu bar → Quit Omna (⌘Q). All processes exit cleanly. Your index, stats, and settings persist.

Uninstall: Drag Omna.app from /Applications to Trash. Your index and settings at ~/Library/Application Support/Omna/ remain — delete that folder manually if you want a clean slate.