# FAQ & Troubleshooting — Omna Help > Common questions and solutions for when something isn't working as expected. Canonical: https://omna.dev/help/faq Common questions and solutions for when something isn't working as expected. --- ## General questions ### What is the Token Tax? The Token Tax is the hidden cost of sending large files to AI. AI models charge by the token (roughly 4 characters = 1 token). A 10,000-row spreadsheet might contain 500,000 tokens — far beyond what any AI can read in one go. Most people either get a rejection error or get an answer based on only the first chunk of their file. Omna finds the relevant rows before the AI sees the file, so you pay for 300 rows instead of 10,000, and get a better answer. ### Does Omna work without an internet connection? Yes. Omna is fully offline. Indexing, slicing, PII masking — everything runs locally. The only time a network connection is needed is when the sliced result is sent to the AI (that's your browser or the AI app's connection, not Omna's). ### Is my data safe? Yes. Nothing leaves your device via Omna. See the [Privacy & Security](07-privacy-and-security.md) doc for the full breakdown. ### Does Omna work on Windows? Not yet. macOS only in v1. Windows is on the roadmap. ### Does the Chrome extension work on Safari or Firefox? Not yet. Chrome only in v1. --- ## Installation issues ### "Installer would like to modify apps on your Mac" — is this safe? Yes. This is a standard macOS prompt for any `.pkg` installer that writes to `/Applications/`. Click Allow. ### The capsule doesn't appear when I open Claude / ChatGPT Check three things: 1. **Is Accessibility permission granted?** Open System Settings → Privacy & Security → Accessibility → confirm Omna is listed and toggled ON. 2. **Is the Omna menu bar icon visible?** Look for the **O** in your menu bar. If it's not there, Omna isn't running — open `/Applications/Omna.app`. 3. **Did you reinstall Omna recently?** After each reinstall, the Accessibility permission needs to be re-granted (remove Omna from the list and add it again). Then Quit and relaunch Omna. ### I granted Accessibility but the onboarding card is still showing Omna checks for Accessibility trust every second. If the card doesn't dismiss within 2–3 seconds of granting permission: 1. Click **"I've enabled it — continue"** on the card. 2. If it warns you that it's still not detected, click **"Continue anyway"** — Omna will work even if the initial detection lagged. 3. Quit Omna (menu bar → Quit) and relaunch it — sometimes macOS needs a process restart to reflect a new Accessibility grant. --- ## File slicing issues ### What's the difference between Slice mode and Advisory mode? Open the extension popup → gear icon → **File Handling**. - **Slice mode** (default): Omna intercepts the file, finds the rows your question needs, masks any PII, and sends only the relevant slice to the AI. You see a result card showing rows sent, token reduction, and how many fields were masked. - **Advisory mode**: Omna does NOT slice the file. The original file goes through unchanged. The only thing Omna does is scan the file for PII with its local scanner — if sensitive data is found, a warning banner appears so you know before you send. Nothing is blocked. Use Advisory mode when you want to send the full file to the AI but still want a heads-up about sensitive data. ### The "N items masked" chip isn't showing on the slice card The amber chip only appears when the native slicer encounters PII it has **never seen before** in this session or prior sessions. If you've dropped the same file before, the names and emails are already in the local registry — the slicer masks them but registers 0 new tokens, so no chip appears. To test with a fresh file: create a CSV with names and email addresses the registry hasn't seen, then attach it. Or clear the registry (`rm ~/Library/Application\ Support/Omna/registry.tsv`, then Quit + relaunch Omna) to reset all prior entries. ### I dropped a file but nothing happened - **Is your question typed in the AI chat box?** Omna reads the question at the moment of drop. If the chat box is empty or the code editor is focused (for Cursor/VS Code), Omna will show a prompt to click the chat box first. - **Is the file format supported?** Check [Supported File Formats](03-supported-files.md). PNG/JPG/JPEG/WEBP/HEIC images are OCR'd and sliced. GIF/BMP/SVG, audio, video, ZIP, and encrypted files are not supported. - **Is the file over 10 GB?** Files above 10 GB are skipped. ### The slice returned irrelevant rows This usually means the question used abstract language that didn't match the data keywords. Try: - Using words that appear literally in the data (column names, values) - For numeric comparisons, be explicit: "over $500" instead of "high-value transactions" - For date ranges, use actual date values: "after 2024-01-01" If Omna's suggestions appear ("Your question didn't match keywords — try asking…"), use those suggestions as a starting point. ### "Native host not available" in the browser extension The Mac app isn't running. Open `/Applications/Omna.app`. If it's already open, try: 1. Quit Omna from the menu bar 2. Reopen it 3. Try the attachment again ### The browser extension shows "Omna timed out" The browser extension waited 60 seconds for the Mac app to finish slicing the file. That 60-second envelope is the extension's outer wait; the Mac app's own slicing budget is shorter — about 45 seconds on a standard Mac (Slow profile) and 30 seconds on a fast Mac (Fast profile). The extra 15 seconds is headroom the extension gives the Mac app for moving the file across Chrome's Native Messaging channel. This usually means a very large un-indexed file ran past the Mac app's budget on a slower machine. Wait for the background indexer to finish the file (progress is in the menu bar), then try again — indexed files use the fast Tier-1 path. On small or already-indexed files this is sub-second; on a 4-million-row indexed parquet the first query after Omna starts is about 20 seconds, then sub-second for every later query while Omna keeps running. ### The slice percentage seems lower than expected Omna reports the actual reduction based on the real token count, using the same tokenizer the AI uses (o200k_base). Differences from what you expect: - Structured data (CSVs with many columns) tokenizes denser than plain text — the "file tokens" baseline may be higher than `filesize / 4` - The output format is clean CSV — more compact than some intermediate formats If you want to see the exact numbers, the result card shows tokens sent vs. total tokens counted. --- ## PII masking issues ### PII isn't being detected PII detection handles common patterns out of the box. Edge cases: - **Unusual name formats:** non-Western names or unusual spellings may not be caught. Custom patterns for enterprise use are on the roadmap. - **Abbreviations:** initials like "J.S." are not detected as names. - **Numbers without context:** a 16-digit number is detected as a credit card only if the surrounding text suggests financial context. ### The masked placeholder appears in the AI's response This is expected behavior when **Shield mode is OFF**. The AI sees `[PERSON_1]` and refers to it by that placeholder. Turn Shield mode ON in the extension popup — Omna will swap placeholders back to real values in the AI's response before you see them. --- ## Indexing issues ### Indexing seems stuck Check the menu bar — if it shows "paused" with a hyphen overlay: - Are you on battery? Indexing pauses on battery. - Is a Zoom/Meet/Teams call active? Indexing pauses during calls. - Is CPU above 70%? Indexing pauses under high load. If none of these apply, check the log: menu bar → **Open log**. ### An indexed file isn't getting Tier 1 speed This can happen if the file's content changed after indexing (Omna uses a content fingerprint — even a single byte change triggers re-indexing). Wait for the re-index to complete. It can also happen if a file was indexed before the HNSW fast-artifact upgrade — Omna falls back to a slower brute-force cosine scan until the indexer back-fills the missing `.hnsw.*` + `.rows` artifacts. Leave Omna running and it will catch up in the background. If you need to force a re-index — for example after raising the row cap setting: 1. Menu bar → **Reveal data folder** to open `~/Library/Application Support/Omna/`. 2. Open `index/` — files are organised into one subfolder per indexed file, named for its content fingerprint. 3. Find the subfolder for the file you want to re-index (the menu bar shows the fingerprint when you're indexing it, or you can read `manifest.json` to map source paths to fingerprints). 4. Move that subfolder to Trash. 5. Quit Omna from the menu bar, then relaunch. The walker re-queues the file and rebuilds it from scratch. You can also do it from the terminal if you know the subfolder name (each indexed file gets one subfolder named after the source file): ```bash rm -rf ~/Library/Application\ Support/Omna/index/ ``` Then quit and relaunch Omna. ### How do I check what's in the index? Open the log (menu bar → Open log) or reveal the data folder (menu bar → Reveal data folder) to browse the `index/` directory. The `manifest.json` file lists every indexed file with its fingerprint, row count, and token count. --- ## Known limitations | Limitation | Status | |---|---| | Screenshots (PNG/JPG/JPEG/WEBP/HEIC) are OCR'd and sliced | OCR via macOS Vision — GIF/BMP/SVG not supported | | Cursor/VS Code require AI chat panel focused (not code editor) | Expected behavior — code editor focus ≠ AI question | | Accessibility permission re-grant needed after each Omna reinstall | Permanent fix requires Apple Developer ID + notarization (in progress) | | Low-power mode takes effect on next Omna launch (not immediately) | macOS thread pool can only be configured at process start | | Very large files (> 2M tokens) may take up to 45 seconds on Slow profile Macs | Index the file first to use the Tier-1 fast path: sub-second on small files, about 20 seconds on a 4M-row parquet for the first query after Omna starts, then sub-second for every later query while Omna keeps running | --- ## Still need help? - Check the log: menu bar → **Open log** — it records every slice, every AX read, every error - Email us: team@omna.dev - Website: omna.dev