# Omna — Mask PII & Kill the Token Tax Before AI Sees It

> Free local-first Mac app that masks PII and slices massive files before sending to Claude, ChatGPT, Gemini, Perplexity or DeepSeek.

Canonical: https://omna.dev/

## What Omna is

Omna is the semantic layer between your data and AI. Two surfaces share one Rust kernel:

- **Omna for Mac** — a free menu-bar capsule that masks PII and slices large files locally before you paste them into Claude, ChatGPT, Gemini, Perplexity, or DeepSeek.
- **Omna for Python** — a Polars/pandas plugin for local semantic search and PII masking. `pip install omna`.

## Why it exists

LLM providers charge by token. Sending raw files means paying the "Token Tax" — paying to send PII, boilerplate, and irrelevant context to a remote model. Omna strips PII and slices files on-device before the request leaves your machine.

## Key properties

- Zero data egress. PII detection and tokenization run on-device (Rust + WebAssembly).
- No API keys, no accounts required for the local features.
- Compatible with Claude, ChatGPT, Gemini, Perplexity, DeepSeek.
- HIPAA- and GDPR-friendly by design — data never leaves the host.

## Links

- Python library: https://omna.dev/library
- Mask PII before LLMs: https://omna.dev/mask-pii-before-llm
- Polars semantic search: https://omna.dev/polars-semantic-search
- Help docs: https://omna.dev/help
- Privacy policy: https://omna.dev/privacy

---

# Omna for Python — Semantic Search & PII Masking for Polars

> The Omna Python library: local-first, Rust-powered semantic search and PII masking for Polars and pandas DataFrames.

Canonical: https://omna.dev/library

## Install

```bash
pip install omna
```

## One-line semantic search

```python
import polars as pl, omna
df = pl.read_parquet("notes.parquet")
df.omna.search("denied claim, prior auth missing", top_k=5)
```

## One-line PII masking

```python
masked = df.omna.mask(columns=["note"])
```

## Why local-first

- Patient data and trade secrets never leave the host
- No API key, no rate limit, no per-call cost
- Runs anywhere Polars runs — laptops, CI, air-gapped boxes

---

# Privacy Policy — Omna

> What we collect (nothing) and what stays on your device.

Canonical: https://omna.dev/privacy

## Summary

Omna is local-first. PII detection, embeddings, semantic search, and file slicing all run on your device. No text, files, or identifiers are sent to an Omna server.

## What we collect

- Anonymous install pings (count only, no PII)
- Voluntary feedback you submit via the feedback form

## What we do not collect

- Your prompts, files, or DataFrames
- Detected PII entities or token mappings
- API keys for third-party LLMs

---

# Feedback — Omna

> Submit bug reports and feature requests.

Canonical: https://omna.dev/feedback

Use the feedback form at https://omna.dev/feedback to submit bugs, feature requests, or general comments.

---

# Polars Semantic Search — One-Line Vector Search for DataFrames

> Add semantic search to Polars DataFrames in one line of Python. Local-first, Rust-powered, zero network calls.

Canonical: https://omna.dev/polars-semantic-search

## The one-line API

```python
import polars as pl, omna
df = pl.read_parquet("clinical_notes.parquet")
df.omna.search("chest pain radiating to left arm", top_k=3)
```

## Benchmarks

- ~12ms p50 latency on 1M rows (M2 MacBook, MiniLM embeddings)
- 0 network calls — runs in your Python process
- HIPAA-compatible by design — no egress, no BAA required

## vs Pinecone / Weaviate / pgvector

Hosted vector DBs are designed for distributed, multi-tenant production search. For analytical Polars pipelines — notebooks, ETL, ad-hoc exploration — they are operationally heavy. Omna trades infrastructure for an in-process Rust kernel.

---

# Polars PII Masking — Mask Names, Emails, MRNs in One Line

> Mask PII in Polars DataFrames locally with a Rust kernel. No regex, no cloud.

Canonical: https://omna.dev/polars-pii-masking

```python
import polars as pl, omna
df = pl.read_parquet("notes.parquet")
masked = df.omna.mask(columns=["note"])
```

Detects names, emails, phone numbers, SSNs, MRNs, addresses. Runs entirely on-device.

---

# Pandas Semantic Search — Local Vector Search for pandas

> Semantic search on pandas DataFrames, in one line of Python, with no API key.

Canonical: https://omna.dev/pandas-semantic-search

```python
import pandas as pd, omna
df = pd.read_parquet("notes.parquet")
df.omna.search("billing dispute", top_k=3)
```

---

# Pandas PII Masking — Redact Personal Data Locally

> Mask PII in pandas DataFrames using a local Rust kernel. No cloud, no API key.

Canonical: https://omna.dev/pandas-pii-masking

```python
import pandas as pd, omna
df.omna.mask(columns=["note"])
```

---

# Mask PII Before Sending Data to an LLM

> Strip names, emails, MRNs, and identifiers before sending a prompt to Claude, ChatGPT, Gemini, Perplexity, or DeepSeek.

Canonical: https://omna.dev/mask-pii-before-llm

Omna masks PII before the request leaves your machine. Two surfaces:

- **Browser extension / Mac app** — intercepts paste into Claude, ChatGPT, Gemini, Perplexity, DeepSeek and replaces PII with reversible tokens.
- **Python** — `df.omna.mask(columns=["note"])` for batch pipelines.

Tokens are mapped on-device. The mapping never leaves your machine.

---

# Mask PII Before Sending to Claude

> Reversibly tokenize PII before pasting into Claude (Anthropic).

Canonical: https://omna.dev/mask-pii-before-claude

Install the Omna extension or Mac app. Paste as usual; PII is replaced with tokens like `[PERSON_1]` before the text reaches Claude. Re-identification happens locally on the response.

---

# Mask PII Before Sending to ChatGPT (OpenAI)

> Reversibly tokenize PII before pasting into ChatGPT.

Canonical: https://omna.dev/mask-pii-before-openai

Omna intercepts paste into chatgpt.com and replaces PII with tokens before the request leaves your browser.

---

# Mask PII Before Sending to Gemini

> Reversibly tokenize PII before pasting into Google Gemini.

Canonical: https://omna.dev/mask-pii-before-gemini

Omna intercepts paste into gemini.google.com and replaces PII with tokens before the request leaves your browser.

---

# HIPAA-Compliant Vector Search

> Run semantic search on PHI without a BAA. Omna is in-process — PHI never leaves the host.

Canonical: https://omna.dev/hipaa-compliant-vector-search

Because Omna runs in your Python process, there is no disclosure to a third party — no BAA required.

---

# GDPR-Compliant Semantic Search for EU Data

> Run semantic search on EU customer data without a data-transfer agreement.

Canonical: https://omna.dev/gdpr-compliant-search

Article 5(1)(c) GDPR demands data minimisation. Omna runs in-process so EU personal data never crosses a border.

---

# Local Semantic Search in Python — No API Keys, No Cloud

> Run semantic vector search entirely on your laptop. No OpenAI keys, no Pinecone.

Canonical: https://omna.dev/local-semantic-search-python

```python
import polars as pl, omna
df = pl.read_parquet("notes.parquet")
df.omna.search("denied claim, prior auth missing", top_k=5)
```

---

# PII Detection in Python — Local, Rust-Powered

> Detect names, emails, phone numbers, SSNs, MRNs, and addresses in Python without sending data to a cloud API.

Canonical: https://omna.dev/pii-detection-python

```python
import omna
entities = omna.detect("Jane Doe, MRN 123456, jane@example.com")
```

---

# Redact Patient Data in Python

> Redact PHI from clinical notes locally with a Rust kernel.

Canonical: https://omna.dev/redact-patient-data-python

```python
df.omna.mask(columns=["note"])
```

---

# Polars + Omna vs Pinecone

> When to use a local Polars-native vector kernel and when to reach for Pinecone.

Canonical: https://omna.dev/polars-vs-pinecone

Use Omna for analytical pipelines, notebooks, and HIPAA/GDPR-sensitive workloads. Use Pinecone for distributed multi-tenant search-as-a-service at production scale.

---

# Polars + Omna vs Weaviate

> When a local Rust kernel beats a hosted vector DB.

Canonical: https://omna.dev/polars-vs-weaviate

Omna runs in-process with no container, no index server, no network hop. Weaviate is the right pick when you need production multi-tenant search at scale.

---

# Local Pinecone Alternative for Python

> Replace Pinecone with an in-process Rust kernel for DataFrame-scale vector search.

Canonical: https://omna.dev/pinecone-alternative-local

Omna gives you Pinecone-style semantic search as a method on Polars and pandas DataFrames — no cluster, no API key.

---

# pgvector Alternative for Analytical Pipelines

> Skip pgvector for DataFrame-scale workloads — run vector search in-process.

Canonical: https://omna.dev/pgvector-alternative

pgvector is excellent for OLTP. For DataFrame-scale analytical workloads, Omna keeps the index in your Python process and avoids the Postgres round-trip.

---

# Semantic Search on Parquet Files

> Search Parquet files by meaning, locally, with one line of Python.

Canonical: https://omna.dev/semantic-search-parquet

```python
pl.read_parquet("docs.parquet").omna.search("renewal cancellation", top_k=5)
```

---

# Semantic Search on CSV Files

> Search CSV files by meaning, locally, with one line of Python.

Canonical: https://omna.dev/semantic-search-csv

```python
pl.read_csv("docs.csv").omna.search("renewal cancellation", top_k=5)
```

---

# Embed a Pandas or Polars DataFrame Locally

> Generate text embeddings for every row of a DataFrame locally, in-process, with a Rust kernel.

Canonical: https://omna.dev/embed-dataframe-locally

```python
df.omna.embed(column="text")  # adds an "embedding" column
```

---

# On-Device PII Redaction

> Redact PII on the device, before any data leaves the host.

Canonical: https://omna.dev/on-device-pii-redaction

Omna's PII engine runs as a Rust library (Python) or WebAssembly module (browser/Mac). No network calls.

---

# Rust-Powered Vector Search for Python

> A Rust kernel exposed to Python via PyO3 — semantic search at Rust speed, with a Pythonic API.

Canonical: https://omna.dev/rust-vector-search-python

Rust kernel + Python bindings = ~12ms p50 on 1M rows on a laptop, with no GIL contention on the hot path.

---

# RAG Without a Vector Database

> Build retrieval-augmented generation pipelines without standing up a vector DB.

Canonical: https://omna.dev/rag-without-vector-db

For most RAG pipelines under 10M chunks, you don't need a vector DB. Index in a DataFrame, search in-process with Omna, pass the top-k to your LLM.

---

# The Token Tax — Why You're Overpaying LLM Providers

> Every byte of PII, boilerplate, and bloat in your prompt is a tax. Omna kills it locally.

Canonical: https://omna.dev/token-tax

LLMs bill by token. Most prompts ship redundant context, full files, and PII the model doesn't need. Omna slices files and masks PII on-device so you only pay for tokens that matter.

---

# Getting Started with Omna — Omna Help

> Omna kills the Token Tax — the hidden cost of sending large files to AI. It finds the relevant rows before the AI ever sees your file, so you pay for 500 rows instead of 500,000, and get a better answer.

Canonical: https://omna.dev/help/getting-started

Omna kills the Token Tax — the hidden cost of sending large files to AI. It finds the relevant rows before the AI ever sees your file, so you pay for 500 rows instead of 500,000, and get a better answer.

This guide takes you from zero to your first slice in under five minutes.

---

## What you need

- A Mac running macOS Sequoia or later
- One of these AI apps installed: Claude Desktop, ChatGPT, Codex, Cursor, or VS Code
- Google Chrome (for the browser extension — optional but recommended)

---

## Step 1 — Download and install

1. Go to **omna.dev** and click **Download for Mac**.
2. Open the downloaded `Omna.pkg` file.
3. The installer will ask you to choose folders for Omna to pre-index. Desktop, Documents, and Downloads are pre-selected. Add any folder that contains files you regularly send to AI. Click **Start Omna**.
4. macOS may show *"Installer would like to modify apps on your Mac"* — click **Allow**. This is standard for any `.pkg` installer.

Omna lands in `/Applications` and starts running in your menu bar immediately.

---

## Step 2 — Grant Accessibility permission

Omna reads your typed question from the AI app's chat box so it knows what to search for. macOS requires you to grant this permission manually.

1. Open Claude Desktop, ChatGPT, Codex, Cursor, or VS Code.
2. A card appears in the center of your screen asking for Accessibility permission.
3. Click **Open Accessibility Settings** → toggle Omna ON.
4. The card dismisses automatically within about a second.

**If the card doesn't appear:** Open System Settings → Privacy & Security → Accessibility → add Omna manually.

---

## Step 3 — Let indexing run

Omna immediately starts building a search index of every file in your chosen folders. For a few hundred files this takes minutes. For millions of rows (like a year of transaction data) it runs overnight.

You can watch progress in the menu bar: click the **O** icon → you'll see the current file and how many rows have been processed.

Omna runs indexing at low priority — by default it caps itself at half your Mac's cores and lowers its scheduler priority so macOS steers the work onto the efficiency cores. Foreground apps stay snappy; fanless MacBooks don't run hot. Switch on Low-power mode (menu bar → Low-power) if you want it to use even fewer cores while you're on a Zoom call or a heavy compile.

---

## Step 4 — Drop your first file

Once Accessibility is granted, the **capsule** — a small floating bar at the bottom of your screen — appears whenever you open a supported AI app.

**The fastest flow:**
1. Type your question in the AI chat box. Example: *"which customers spent over $10,000 last quarter?"*
2. Drag your CSV (or Excel, PDF, Word doc, etc.) from Finder and drop it onto the capsule.
3. Omna finds the relevant rows — usually in under a second for indexed files.
4. The sliced file attaches itself to the chat. Hit Send.

You'll see a result card showing how many tokens were cut and roughly how much that saves in API cost.

---

## Step 5 — Install the Chrome extension (optional but recommended)

The Chrome extension adds Omna directly to your browser — useful when using AI on the web (claude.ai, chatgpt.com, Gemini, Perplexity, DeepSeek).

1. Visit the Chrome Web Store and search for **Omna**.
2. Click **Add to Chrome**.
3. The Omna icon appears in your Chrome toolbar.

With the extension:
- PII (names, emails, IDs) is masked before it leaves your browser — on every AI site automatically.
- Dropping a file on the AI site's attachment button triggers the same slicing as the desktop capsule, silently, with no extra steps.

The extension requires the Mac app to be running for file slicing. PII masking works independently.

---

## What's next

- [Supported AI Apps](02-supported-apps.md) — full list of where Omna works
- [Supported File Formats](03-supported-files.md) — what you can drop
- [How Slicing Works](04-how-slicing-works.md) — what happens inside the black box
- [FAQ & Troubleshooting](09-faq-and-troubleshooting.md) — if something isn't working

---

# Supported AI Apps — Omna Help

> Omna works in two places: the **desktop capsule** (the Mac app) and the **browser extension** (Chrome). Each has its own list of supported apps.

Canonical: https://omna.dev/help/supported-apps

Omna works in two places: the **desktop capsule** (the Mac app) and the **browser extension** (Chrome). Each has its own list of supported apps.

---

## Desktop capsule — Mac apps

The capsule appears at the bottom of your screen when any of these apps is open.

| App | Where to download | Notes |
|---|---|---|
| **Claude Desktop** | claude.ai → Download | Anthropic's official Mac app |
| **ChatGPT** | chatgpt.com → Download | OpenAI's official Mac app |
| **Codex** | Available via OpenAI | OpenAI's AI agent app |
| **Cursor** | cursor.sh | AI code editor — use the AI chat panel, not the code editor |
| **VS Code** | code.visualstudio.com | Works with any AI chat extension (Copilot, Gemini Code Assist, etc.) — use the chat panel |

### IDE note (Cursor and VS Code)

Cursor and VS Code are code editors that have an AI chat sidebar built in. The capsule works correctly when **the AI chat input is focused** at the time you drop a file.

If you're typing in the code editor (not the chat panel) when you drop, Omna will say *"Click the chat box first so I can read your question."* Switch to the chat input and drop again.

---

## Browser extension — AI websites

The Chrome extension works on these sites when you're using AI in the browser:

| Site | What the extension does |
|---|---|
| **claude.ai** | PII masking + file slicing |
| **chatgpt.com** | PII masking + file slicing |
| **gemini.google.com** | PII masking + file slicing |
| **perplexity.ai** | PII masking + file slicing |
| **chat.deepseek.com** | PII masking + file slicing |

The extension works on all Chrome sites for PII masking. The list above is where file interception (automatic slicing on attachment) is fully wired.

---

## Does the extension need the Mac app?

**PII masking** works without the Mac app — the extension runs the masking engine locally in Chrome via WebAssembly.

**File slicing** requires the Mac app to be installed and running. The extension sends the file to the Mac app for slicing, then swaps the original with the sliced version before the AI site sees it.

---

## Apps not currently supported

The following are common AI tools that are not yet supported in v1:

- **Notion AI** — AI inside Notion (on the roadmap)
- **GitHub Copilot in VS Code** — use the VS Code support above; the Copilot Chat panel works
- **Windsurf** (Codeium) — on the roadmap
- **Gemini for Mac** — on the roadmap if a desktop app ships
- **Any web browser other than Chrome** — Safari and Firefox extensions are on the roadmap

---

## Coming soon

We're adding new apps regularly. If an AI app you use isn't on this list, you can still use Omna's file slicing by:
1. Running the slice from the desktop capsule (drop a file onto the capsule while a supported app is open)
2. Using the output file that Omna saves to your Downloads folder

Have a specific request? Drop us a note at omna.dev.

---

# Supported File Formats — Omna Help

> Omna can slice any of these file types before sending to AI. Each format is handled differently based on its structure.

Canonical: https://omna.dev/help/supported-files

Omna can slice any of these file types before sending to AI. Each format is handled differently based on its structure.

---

## Tabular files (rows and columns)

These are sliced row-by-row. Omna finds the rows most relevant to your question and sends only those.

| Format | Extensions | Notes |
|---|---|---|
| **CSV** | `.csv` | Most common. All columns preserved. |
| **Excel** | `.xlsx`, `.xls`, `.xlsb` | All sheets are concatenated into one table. |
| **OpenDocument Spreadsheet** | `.ods` | Same as Excel handling. |
| **Parquet** | `.parquet` | Column-store format common in data engineering. Fully supported — no size limit beyond the 10 GB file cap. |

**Output format:** A clean CSV with a header row and only the relevant rows. Column names are preserved exactly as they appear in the original.

**What counts as a "relevant row":** Omna uses a combination of keyword matching (BM25) and semantic similarity (sentence embeddings) to score every row against your question. Rows with scores below a minimum threshold are dropped. For numeric questions ("over $500", "between 10 and 20"), an exact arithmetic filter runs first — all rows that arithmetically satisfy the condition are kept, regardless of semantic score.

---

## Documents (text with structure)

These are sliced section-by-section. Omna finds the sections most relevant to your question.

| Format | Extensions | Notes |
|---|---|---|
| **Word** | `.docx`, `.doc`, `.odt`, `.rtf` | Sliced by paragraph or heading section. |
| **PDF** | `.pdf` | Sliced by page. Each page becomes one searchable unit. |

**Output format:** A `.txt` file with structural markers. Word docs include `[§ Heading Name]` markers before each section. PDFs include `[p. N]` markers before each page's content.

**Why PDFs are sliced by page:** Unlike tabular data where each row is an independent fact, PDFs contain flowing text where context within a page matters. Splitting mid-paragraph would break meaning. One page = one chunk is a safe, predictable unit.

---

## Plain text files

These are sliced line-by-line.

| Format | Extensions | Notes |
|---|---|---|
| **Plain text** | `.txt`, `.md`, `.log` | Each non-empty line is one searchable unit. |
| **JSON** | `.json` | Each top-level array element or top-level object key is one unit. |

**Markdown files:** Treated as plain text. Omna doesn't parse markdown structure — each line is indexed independently. For large `.md` files with clear headings, results will typically cluster around the relevant sections naturally.

**Log files:** Log line format varies widely. Omna indexes each line as a unit and uses keyword + semantic search to surface the relevant entries. Works well for error logs, access logs, and structured log lines.

---

## File size limits

| Limit | Value | Why |
|---|---|---|
| Maximum file size | **10 GB** | Hard cap per file |
| Maximum rows for full indexing | **5,000,000 rows** | Above this, only BM25 keyword index is built (no embeddings) |
| Minimum row length for embeddings | **50 tokens** | Very short rows (like single IDs) are BM25-only |

Files above 5M rows can still be sliced — the keyword search runs on all rows, but the semantic reranking step only applies to the BM25 survivors.

---

## What is NOT supported

### Screenshots and images (OCR-sliced)

`.png`, `.jpg`, `.jpeg`, `.webp`, `.heic` files are supported via OCR.

When you drop a screenshot onto the capsule or attach it in the browser extension, Omna uses macOS Vision to extract the text, then slices and masks it exactly like a `.txt` file. The AI receives extracted text (~200–400 tokens) instead of the raw image (~1,600 Vision API tokens).

AI Vision APIs charge ~1,600 tokens per image regardless of content. OCR + slicing can cut that by 70–90% when the image contains relevant text.

**Unsupported image formats:** `.gif`, `.bmp`, `.svg` — these are not screenshot formats and are released to the AI unchanged.

### Other unsupported formats

| Format | Status |
|---|---|
| Images (`.gif`, `.bmp`, `.svg`) | Not supported — not screenshot formats |
| Audio (`.mp3`, `.m4a`, `.wav`) | Not supported |
| Video (`.mp4`, `.mov`) | Not supported |
| Encrypted / password-protected files | Not supported — Omna cannot read encrypted content |
| ZIP / RAR archives | Not supported — extract first, then drop the individual file |
| Binary files (`.exe`, `.bin`, `.dmg`) | Not supported |

---

## Extension vs. desktop app — same formats?

Yes. The browser extension uses the same slicing engine as the desktop capsule (the Mac app). When you attach a file on claude.ai or chatgpt.com, the extension sends it to the Mac app for slicing and swaps the result in — same formats, same quality, same output.

**One difference:** The extension does its own PDF and Word text extraction in Chrome (using pdfjs-dist and mammoth) before sending to the Mac app. The Mac app handles all formats natively. End result for the user is identical.

---

## How Omna picks the output format

| Input | Output |
|---|---|
| Tabular (CSV, Excel, Parquet) | `.csv` — header + relevant rows |
| PDF | `.txt` — page markers + relevant page content |
| Word / RTF / ODF | `.txt` — section markers + relevant sections |
| Plain text / log / markdown | `.txt` — relevant lines |
| JSON | `.json` — relevant top-level elements |
| Image (PNG/JPG/JPEG/WEBP/HEIC) | `.txt` — OCR'd text, relevant lines sliced |

The output file is attached to the AI chat as if you'd attached it yourself. The AI sees the sliced file — it never sees the original.

---

# How Slicing Works — Omna Help

> Understanding what Omna does inside the black box — so you know what to expect and how to get the best results.

Canonical: https://omna.dev/help/how-slicing-works

Understanding what Omna does inside the black box — so you know what to expect and how to get the best results.

---

## The problem: the Token Tax

AI models (Claude, ChatGPT, Gemini) charge by the token. One token is roughly 4 characters of text. A 100,000-row CSV file might contain 10 million tokens. Sending the whole file to Claude costs roughly $30 and often fails entirely because Claude's context window only fits 200,000 tokens.

Most people deal with this by:
- Sending just the first N rows (the AI gets an arbitrary slice, not the relevant one)
- Summarizing manually (time-consuming, loses detail)
- Giving up (the question doesn't get answered)

Omna's approach: **find the 200–500 rows that actually answer your question, and send only those.** The AI gets full-resolution relevant data. You pay for a fraction of the cost. The answer is better.

---

## The two paths: Tier 1 and Tier 2

### Tier 1 — Pre-indexed files (fast path)

If you've dropped this file before, or if it lives in a folder Omna watches, it's already been indexed in the background. "Indexed" means Omna has pre-computed a semantic embedding (a 768-number fingerprint of meaning) for every row **and** built an HNSW (Hierarchical Navigable Small World) approximate-nearest-neighbour graph over those embeddings.

When you drop the file with a question:
1. Omna embeds your question (same 768-number format)
2. Queries the HNSW graph for the nearest neighbours in **O(log N)** — the search jumps directly to nearby vectors instead of scoring every row
3. Fetches the matched row text from a memory-mapped `.rows` random-access store (so Tier 1 reads only the rows that survived, not the whole file)
4. Drops rows below a minimum similarity threshold (0.3 cosine similarity, proven across a 113-test benchmark)
5. If more than 70% of rows survive the threshold (your question is very broad), applies a tighter filter: `max(0.3, top_score × 0.6)`
6. Returns the survivors in order of relevance, within the token budget

If the HNSW + `.rows` artifacts haven't been back-filled yet (a file indexed before the fast-artifact upgrade and not yet rebuilt), Omna automatically falls back to a parallel brute-force cosine scan over every embedded row. Same answer, slower path.

**How fast is Tier 1 in practice?**

- **Small files** (a few thousand rows, a few hundred MB of embeddings): sub-second.
- **Large files today** (4-million-row parquet, ~6 GB of embeddings): about 20 seconds on the first query after Omna starts, then sub-second for every later query on the same file while Omna keeps running. The first-query cost is dominated by loading the HNSW segment graphs from disk.
- An always-warm in-memory cache (so the first query is fast too) is a tracked open item — see USER_JOURNEY §5 Step 8 for the current spec.
- **Numeric range questions** ("over $500", "between X and Y") take the brute-force arithmetic path instead of HNSW — see *Numeric questions* below.

The point of Tier 1 is that Omna never has to *re-read or re-embed* your file when you ask a question. The vectors and the search graph already exist on disk — Tier 1 just walks them.

### Tier 2 — Live drop (15–45 seconds)

If the file has never been indexed, Omna processes it on the fly:

**On a standard Mac (Slow profile — below 1,000 rows/second embedding speed):**
1. BM25 keyword scan — reads every row, scores by keyword frequency and rarity. Takes 1–7 seconds depending on file size.
2. Keeps rows that score at least 15% of the top BM25 score. Drops everything else.
3. From the survivors, takes up to 1,000 rows.
4. Runs semantic embedding on those 1,000 rows.
5. Reranks by cosine similarity to your question.
6. Returns the top rows within the token budget.

**On a fast Mac (Fast profile — 1,000+ rows/second):**
1. Skips BM25 entirely.
2. Embeds up to 3,000 rows directly (stratified sample if the file has more).
3. Ranks by cosine similarity.
4. Returns top rows within the token budget.

After a Tier 2 slice, the background indexer immediately starts embedding all rows. The next time you drop the same file, it's a Tier 1 slice.

---

## Numeric questions — exact arithmetic filter

For questions with explicit comparisons ("transactions over $500", "between 100 and 200", "less than $10"), pure semantic search is wrong — language models cannot compare numbers. $389 and $621 are semantically identical ("they're both dollar amounts near $500") but arithmetically different.

Omna detects range questions and runs an **exact arithmetic filter** before any semantic step:
1. Identifies the numeric column (named in your question, or the only numeric column, or asks you to clarify if ambiguous)
2. Filters to rows that arithmetically satisfy the condition: `amount > 500`
3. This set is authoritative — cosine similarity only *orders* the results, it cannot remove a row that passes the arithmetic test

**Why this matters:** If you ask "find transactions over $500" and 11 of your 50 rows qualify, you get exactly those 11 rows — not 36 rows where some are over $500 and some aren't, which is what pure semantic search would return.

---

## What the result card shows

After every slice, a result card appears. It classifies the result into one of four scenarios:

| Scenario | Condition | What it means |
|---|---|---|
| **Token Tax killed** | File fits in Claude's window; Omna sent a small relevant slice | Real dollar savings — you pay for the slice, not the file |
| **All rows matched** | File fits; question matched most rows (broad question) | Minimal filtering — card shows actual cost on both sides |
| **Token Tax crushed** | File is bigger than Claude's 200K window; Omna's slice fits | Big savings — baseline is the truncated 200K, not the full file |
| **Token Tax redirected** | File is bigger than 200K; even Omna's slice fills the window | Same token cost, but Omna's 200K contains the *relevant* rows, not the first arbitrary rows |

The savings math always uses Claude's real context window (200K tokens) as the baseline. We never show savings based on a number Claude would have rejected — that would be fictional.

---

## Token budget

Omna does **not** trim the slice to a fixed token target. Every row that matches your question — by keyword, by semantic similarity, or by the exact arithmetic filter — is kept in the output. If your question has 11 matches, you get all 11. If it has 50,000 matches, you get all 50,000.

The AI you're sending the slice to (Claude, ChatGPT, etc.) enforces its own context-window limit. Claude Sonnet's window is 200,000 tokens; if the slice exceeds that, the AI itself truncates from the end. The result card calls this "Token Tax redirected" — same token cost, but the rows in the window are the *relevant* ones, not the first arbitrary ones.

The earlier "100,000 token output" cap that lived in different files for different surfaces caused row counts to disagree between the website, the desktop app, and the browser extension. It was removed on 2026-05-20 so every surface returns the same slice for the same question. See USER_JOURNEY §12.1 for the current rule.

---

## Weak keyword results (BM25 found nothing)

If fewer than 10 rows survive the BM25 step, your question likely used words that don't appear in the data. Omna shows suggestions based on your file's actual column names and sample values:

> *"Your question didn't match any keywords in this file. Based on your data, try asking:*
> *— 'trips where distance is over 20 miles'*
> *— 'fares above $50 with zero tip'"*

Try rewording and drop the file again. If BM25 still finds nothing on the second attempt, Omna falls back to pure semantic search on a random sample of 5,000 rows.

---

## Background indexing

The background indexer runs silently while you work. It:
- Watches your chosen folders for new or changed files
- Processes files in order of size (smaller files first, so you can query them sooner)
- Pauses automatically when you're on battery, your CPU is over 70%, or you're on a Zoom/Meet/Teams call
- Runs at low priority — capped at half your Mac's cores by default (30% in Low-power mode) and scheduled at a background QoS so macOS steers the work toward efficiency cores
- Stores a small set of artifacts per indexed file: `index.bm25` (keyword index), `index.embed` (768-dim vectors), `index.hnsw.segs` (segmented HNSW graph), `index.rows` (memory-mapped row-text store for fast Tier-1 lookup), and `index.fingerprint` (content hash for change detection)
- Never re-indexes a file unless its content changes (it uses a content fingerprint, not the file name)

Each indexed file gets its own subfolder under `~/Library/Application Support/Omna/index/`, named after the source file. The default disk cap is 50 GB across all subfolders.

---

## PII masking during slicing

Before the sliced rows are sent to the AI, Omna masks personal information:
- Names, emails, phone numbers, addresses
- Social Security numbers, passport numbers
- Credit card numbers, bank account numbers
- Healthcare data, employment data, credentials

Masked text looks like: `[PERSON_1]`, `[EMAIL_1]`, `[PHONE_1]`. The AI receives the masked version. Omna's local token registry maps each placeholder back to the real value so results stay meaningful.

You can turn PII masking off in the menu bar if you're working with non-sensitive data.

---

# Browser Extension — Omna Help

> The Omna Chrome extension brings the Token Tax protection directly into your browser — no dragging to the capsule, no switching apps.

Canonical: https://omna.dev/help/browser-extension

The Omna Chrome extension brings the Token Tax protection directly into your browser — no dragging to the capsule, no switching apps.

---

## What it does

Two independent capabilities, both running locally in Chrome:

### 1. PII Masking (always on)

As you type in any AI chat box on claude.ai, chatgpt.com, Gemini, Perplexity, or DeepSeek, Omna watches for personal information:

- Names, emails, phone numbers, addresses
- ID numbers, passport numbers, driver's license numbers
- Credit card numbers, bank accounts, IBAN numbers
- Healthcare data, salary information, credentials and API keys

When PII is detected, it is replaced with a placeholder (`[PERSON_1]`, `[EMAIL_1]`, etc.) before the text leaves your browser. The AI sees the placeholder. Omna keeps a local registry that maps each placeholder back to the real value so results stay readable.

**Shield mode:** When Shield is ON, if the AI responds with `[PERSON_1]` in its answer, Omna swaps it back to the real name before it reaches your screen. The AI never knew the name; you see the name. Shield is off by default — turn it on in the extension popup.

**Wire-level interception:** Masking happens at the network level (the `fetch` call), not at the UI level. This means it works even on sites that use complex web frameworks, shadow DOM, or unconventional input patterns. The text is masked before the HTTP request is sent.

### 2. File Slicing (on AI attachment)

When you attach a file to an AI site's upload button, Omna intercepts it before the site sees it:

1. You click the attachment button and select your CSV, Excel, PDF, or Word file.
2. Omna captures the file at the browser level before it's submitted.
3. The extension sends the file to the Mac app (running in the background) for slicing.
4. The Mac app slices the file using your previously typed question as the search query.
5. The sliced file is swapped in — the AI site receives the sliced version, never the original.
6. A result banner appears above the chat composer showing how many tokens were cut.

**Zero extra clicks.** You attach a file the same way you always did. Omna's interception is invisible.

---

## Supported sites for file slicing

| Site | File slicing | PII masking |
|---|---|---|
| claude.ai | ✅ | ✅ |
| chatgpt.com | ✅ | ✅ |
| gemini.google.com | ✅ | ✅ |
| perplexity.ai | ✅ | ✅ |
| chat.deepseek.com | ✅ | ✅ |
| All other Chrome sites | — | ✅ (PII masking only) |

---

## The extension popup

Click the Omna icon in your Chrome toolbar to open the popup:

- **Token savings:** how many tokens Omna has trimmed in this browser session and roughly what that's saved in API cost
- **Compression ratio:** percentage reduction — e.g., "77% compression" means you sent 23% of the original tokens
- **Fields masked:** how many PII fields the native slicer has masked across file attachments this session
- **Claim your spot:** enter your email to reserve free Omna access during early access (first 10,000 users)
- **Settings (gear icon):**
  - **Protection:** Auto-mask PII in chat, Scrub PII from files, Shield mode
  - **File Handling:** Choose between **Slice mode** and **Advisory mode** (see below)

---

## Slice mode vs Advisory mode

Open the popup → gear icon → **File Handling** to choose how Omna handles file attachments.

**Slice mode** (default): Omna intercepts the file, finds only the rows relevant to your question, masks any PII, and swaps in a smaller "surgical copy." The AI sees the slice — never the full file. A result card shows rows sent, token reduction, and how many fields were masked.

**Advisory mode**: Omna does not slice the file. The original goes through unchanged. Omna only runs its local PII scanner — if sensitive data is found, a warning banner appears before you send. Use this mode when you want to send the full file but still want a heads-up about sensitive content.

The toggle takes effect immediately — no page reload needed.

---

## Does the extension work without the Mac app?

**PII masking works without the Mac app.** The masking engine runs as WebAssembly directly in Chrome — no network calls, no Mac app required.

**File slicing requires the Mac app.** The extension sends the file to the Mac app via Chrome's Native Messaging protocol (a secure, local-only channel). If the Mac app isn't running, the extension releases the file normally and shows a brief message: *"Omna is not running — file sent without slicing."*

---

## What the result banner shows

After a successful slice, a banner appears above the AI chat composer:

- **Token Tax killed** (green): file was within Claude's context window; Omna sent a small relevant slice — real savings
- **Token Tax crushed** (green): file was too big for Claude's window; Omna's slice fits cleanly under the limit
- **Token Tax redirected** (amber): even Omna's slice fills the window — same token cost, but the right rows are in that window instead of arbitrary ones
- **All rows matched** (blue): your question matched *every* row in the file — nothing was filtered out, shown for transparency. (If even one row was dropped, the scenario is "Token Tax killed" instead.)

The banner shows: rows sent vs. total rows, token reduction percentage, estimated dollar savings, and — when new PII fields were masked during slicing — an amber **"N items masked"** chip. It disappears after a few seconds or when you click the × button.

---

## Privacy

Everything happens locally:
- The masking engine runs as WebAssembly in Chrome — no server involved
- File slicing goes Mac app → sliced file → AI site (the original file never leaves your machine)
- No analytics, no telemetry, no data collection
- PII placeholders and the registry mapping them back to real values are stored in session memory only — they clear when you close the tab or the browser

---

# Desktop App — Omna Help

> The Omna desktop app is a Mac menu-bar app that runs silently in the background. It has three parts: the **capsule**, the **background indexer**, and the **menu bar**.

Canonical: https://omna.dev/help/desktop-app

The Omna desktop app is a Mac menu-bar app that runs silently in the background. It has three parts: the **capsule**, the **background indexer**, and the **menu bar**.

---

## 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](04-how-slicing-works.md))
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](04-how-slicing-works.md))
- **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](04-how-slicing-works.md) 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`** — 768-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 50 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.

---

# Privacy & Security — Omna Help

> Omna is built on a single principle: **your data never leaves your device.** This page explains exactly what Omna does and doesn't do with your data.

Canonical: https://omna.dev/help/privacy-and-security

Omna is built on a single principle: **your data never leaves your device.** This page explains exactly what Omna does and doesn't do with your data.

---

## The core guarantee

- **Zero network calls.** Omna does not send your data to any server — not Omna's servers, not OpenAI's, not Google's, not anyone else's. The only network traffic Omna generates is when you explicitly send a message to an AI app. Even then, Omna only sends the *sliced* (relevant rows) version, not the original file.
- **Zero telemetry.** Omna does not phone home with usage data, crash reports, analytics, or any other information about how you use it.
- **Zero cloud storage.** Your files, your index, your token registry — all stored locally on your Mac.

---

## What Omna does with your files

1. **Reads your files** to build a search index. Files are read from the folders you chose during install (or added later via the menu bar).
2. **Stores index artifacts** in `~/Library/Application Support/Omna/index/`. These are:
   - BM25 keyword index (stores word frequencies per row — not the original text)
   - Embedding vectors (768 numbers representing the semantic meaning of each row — not the original text)
   - The masked text of each row (PII replaced with placeholders — not the original text)
3. **Never uploads** your files, their contents, or their index artifacts anywhere.

The original file content is not stored in the index. If you delete the source file, the index artifacts are the only trace — and they are on your machine.

---

## At-rest protection

Omna does **not** ship its own encryption layer. There is no app-level encryption, no macOS Keychain integration, no separate key escrow. At-rest protection comes from two layers that the operating system provides:

- **Per-user POSIX permissions.** All Omna data lives under your user account's `~/Library/` directory, owned by you and not readable by other local users. Slice files (`~/Library/Caches/Omna/slices/`) are written with stricter `0600` (owner read+write only) inside a `0700` directory.
- **FileVault** (if you have it enabled). FileVault encrypts the entire startup disk — every file, including Omna's, is unreadable without your account password while the disk is locked. macOS does not let Omna or any third-party app turn FileVault on for you; it's a System Settings → Privacy & Security → FileVault toggle.

For most personal use this is the right level. For enterprise deployments with a stricter compliance bar, centrally-pushed policy and audit-log export are on the enterprise-tier roadmap (see below).

---

## PII masking — how it works

When Omna processes text for masking, indexing, or slicing, it scans every row with a **six-layer detection engine** written in Rust — fully on-device, no cloud NLP, no API calls. The same engine runs in the Mac app, the browser extension, and the Python library.

**The six layers:**

1. **Patterns + validators** — emails, phones, SSNs, credit cards, IBANs, and 30+ international ID schemes, *checksum-verified* (Luhn, IBAN mod-97, Aadhaar, NHS, AU TFN/ABN, …) so a real ID is caught and a random look-alike isn't.
2. **Secrets** — 220+ rules (AWS keys, GitHub tokens, JWTs, private keys, database connection strings) with entropy checks.
3. **On-device AI model** — catches contextual personal data no pattern can: a bare name in a sentence, an address, medical context.
4. **Fusion** — resolves overlaps and links the same person across a document.
5. **Policy** — reversible `[PERSON_1]`-style tokens for personal data; **secrets are always redacted irreversibly** and never recoverable.
6. **Audit** — every decision is logged (type, layer, confidence) without ever storing the original value.

**What Omna detects — 30+ data types, plus 220+ secret kinds:**

| Group | Examples |
|---|---|
| People & contact | Names, dates of birth, emails, phone numbers, physical addresses, personal URLs |
| Government & national IDs | SSN, passport, driver's license, tax ID, national IDs — checksum-validated |
| Financial | Credit cards, bank accounts, IBAN, crypto wallets, salary / compensation |
| Health | Medical record numbers, insurance IDs, medical license numbers, diagnoses |
| Employment | Employee IDs, HR / compensation records |
| Digital & network | IP addresses, MAC addresses, device IDs |
| Secrets & credentials | 220+ kinds — API keys, AWS keys, GitHub tokens, JWTs, passwords, private keys — always irreversibly redacted |

**Masked text looks like:** `John Smith` → `[PERSON_1]`, `john@example.com` → `[EMAIL_1]`, an AWS key → `[REDACTED:AWS_KEY]` (irreversible).

**The token registry** maps each placeholder back to the original value. It lives in session memory only (for the browser extension) or on your local machine (for the desktop app). It never leaves your device.

**Multi-name detection:** If a sentence contains multiple names ("recommend Smith, not Johnson"), Omna detects and masks both — it handles contrastive patterns like "X not Y", "X vs Y", "rather than Z", "instead of W".

---

## Accessibility permission — why Omna needs it

macOS requires Accessibility permission for any app that reads text from another app's UI. Omna uses this permission for one specific purpose: **reading the question you typed in the AI chat box at the moment you drop a file.**

Omna does not:
- Log your keystrokes
- Read text from other applications (only the focused AI app while Omna's capsule is active)
- Store what you typed beyond the current drop session
- Run in the background reading anything unless an AI app is foregrounded and the capsule is active

The Accessibility permission is read-only for Omna. It never modifies the AI app's UI. (Writing — the ⌘V paste of the sliced file — uses the standard macOS clipboard, which does not require Accessibility permission.)

---

## What's stored locally

| Location | Contents | When deleted |
|---|---|---|
| `~/Library/Application Support/Omna/index/<subfolder>/` | Per-file `index.bm25` + `index.embed` + `index.hnsw.segs` + `index.rows` + `index.fingerprint`; the masked row text lives inside the BM25 + rows files | When you remove the folder from watch list, or when the 50 GB cap triggers LRU eviction |
| `~/Library/Application Support/Omna/registry.tsv` | Persistent `[PERSON_N] ↔ original` map (so the same name keeps the same token across sessions) | Never — deleting this file resets all placeholders |
| `~/Library/Application Support/Omna/watch_folders.json` | The list of folders you chose to index | Updated whenever you add or remove a folder |
| `~/Library/Application Support/Omna/stats.json` | Lifetime token count, files sliced count | Never (persists across restarts) |
| `~/Library/Application Support/Omna/preferences.json` | PII masking on/off, low-power mode, slice-vs-advisory mode | Never (persists across restarts) |
| `~/Library/Application Support/Omna/machine_profile.json` | Benchmark result (rows/second, Fast/Slow profile) | Never (measured once at install) |
| `~/Library/Application Support/Omna/omna.log` | Application logs | Rotated at 50 MB — the live log is renamed to `omna.log.1` (overwriting any prior `.1`) and a fresh log is started. At most two files on disk. |
| `~/Library/Caches/Omna/slices/` | Sliced output files (sent to AI). Directory is `0700`, files are `0600` — owner-only. | Automatically after 7 days, or when cache exceeds 500 MB |
| Chrome extension local storage | Token savings stats, claimed spot rank | Cleared when you remove the extension |

---

## macOS permissions summary

| Permission | Why | When granted |
|---|---|---|
| **Accessibility** | Read typed question from AI chat box | First launch — you grant manually in System Settings |
| **Folder access** | Read files for indexing | During install — you pick folders via Finder picker, which implicitly grants access |
| **Native Messaging** | Chrome extension ↔ Mac app communication | Automatic — registered during install, local-only |

Omna requests no other macOS permissions. No camera, no microphone, no contacts, no location, no Photos.

---

## Enterprise considerations

For teams that need centralized policy:
- PII masking categories and sensitivity levels can be configured centrally and pushed to all machines (enterprise tier — coming)
- The audit log of masking activity is stored locally and can be exported (coming)
- No data leaves the machine in any tier — the on-device guarantee is unconditional

---

# Pricing & Savings Math — Omna Help

> How Omna calculates and displays token savings — and what the numbers actually mean.

Canonical: https://omna.dev/help/pricing-and-savings

How Omna calculates and displays token savings — and what the numbers actually mean.

---

## The Token Tax

AI models charge per token. One token ≈ 4 characters. Here's what a large file costs to send directly:

| File | Tokens | Claude Sonnet cost (input) |
|---|---|---|
| 1,000-row CSV | ~50,000 | ~$0.15 |
| 10,000-row CSV | ~500,000 | Rejected — exceeds context window |
| 1M-row parquet | ~50,000,000 | Rejected — exceeds context window |

Claude's context window is 200,000 tokens. Files larger than that are rejected before any billing occurs. Most users hit this wall constantly.

---

## What Omna changes

Instead of sending the whole file, Omna sends only the relevant rows — typically 100–500 rows, fitting comfortably within the token budget:

| Without Omna | With Omna |
|---|---|
| Full 50,000-row file: rejected or $15 | 300 relevant rows: $0.009 |
| Claude reads the first 200K tokens (arbitrary rows) | Claude reads the top 200K tokens (relevant rows sorted first) |
| Answer may hallucinate missing data | Answer is grounded in the matching rows |

---

## The four savings scenarios

Omna classifies every slice into one of four scenarios and shows honest math for each.

### Token Tax Killed — small file, narrow query

Your file fits in Claude's 200K window, and Omna found a small relevant slice.

**Example:** 1,545 tokens in a 50-row transaction file. Question: "transactions over $500". Slice: 11 rows, 361 tokens.

```
Without Omna:  $0.005  (1,545 tokens × $3.00 / 1M)
With Omna:     $0.001  (361 tokens × $3.00 / 1M)
Token Tax saved: $0.004
Token reduction: −77%
```

### All Rows Matched — small file, broad query

Your file fits in the window, but your question matched most of the rows — Omna kept almost everything.

**Example:** 50-row file, question "show me all transactions." Omna returns 48 rows.

```
Without Omna:  $0.005
With Omna:     $0.005  (nearly the same — honest reporting)
Token Tax saved: ~$0
```

Omna shows this honestly rather than inflating the savings number. The value here is PII masking and structured attachment, not token reduction.

### Token Tax Crushed — big file, narrow query

Your file is bigger than Claude's 200K window. Omna's slice fits cleanly under the limit.

**Example:** 15,000-row finance CSV, 1.74M tokens. Question: "which firms are based in NYC?" Slice: 80 rows, 82K tokens — well under the 200K window.

```
Without Omna baseline: $0.60  (200K tokens — what Claude would truncate to)
With Omna:             $0.25  (82K tokens)
Token Tax saved: $0.35
```

**Why the baseline is 200K, not the full file:** Claude would never process 1.74M tokens — it would reject the request. The realistic "without Omna" scenario is you sending the first 200K tokens and getting an answer based on arbitrary rows.

### Token Tax Redirected — big file, broad query

Your file is bigger than 200K AND even Omna's relevant slice exceeds 200K. Same token cost either way — but Omna's 200K contains the *relevant* rows, not the first arbitrary ones.

```
Without Omna: $0.60  (first 200K tokens — arbitrary rows)
With Omna:    $0.60  (top 200K tokens — ranked by relevance)
Token Tax saved: $0 in cost, but quality win
```

The result card labels this "Token Tax redirected into relevance" with an amber pill. No fake dollar amount is shown — the value is answer quality, not cost.

---

## Pricing rates used

| Model | Input rate | Used for |
|---|---|---|
| Claude Sonnet 4.6 | $3.00 / 1M tokens | Desktop capsule result card; browser extension popup |

Rates are updated when Anthropic changes pricing. The rate lives in one place per surface: `extension/src/pricing.ts` for the browser extension, and `native/src/card.rs` (`CLAUDE_SONNET_INPUT_USD_PER_M_TOKENS`, line 101) for the desktop capsule and tray. Both constants hold the same value.

Output tokens (Claude's response) are not included in Omna's savings math. Omna only affects what Claude *reads*, not what it *writes*.

---

## The lifetime counter

The menu bar shows:
```
1.2M token tax intercepted
~$3.60 on API · ~240 extra prompts
47 files sliced · 4m ago
```

- **Token tax intercepted:** cumulative tokens trimmed across all slices since install
- **~$X on API:** estimated API cost of those trimmed tokens at Claude Sonnet rates
- **~X extra prompts:** rough estimate of how many additional Claude messages that cost would have paid for (at average prompt size)
- **Files sliced:** total number of file drops processed

These numbers count up permanently and survive app restarts. They're stored in `~/Library/Application Support/Omna/stats.json`.

---

## What "theoretical" means

Sometimes the result card shows savings labeled as "Theoretical." This happens when the file is small enough to fit in Claude's window but you're on a free Claude plan with no API billing. In that case, the dollar savings are real for API users but not applicable to free/paid-plan users who aren't billed per token.

Omna never claims savings based on token counts that Claude would have rejected (files over 200K tokens). If the file would have been rejected before any billing, the "without Omna" baseline is capped at 200K tokens.

---

## Omna pricing

- **Free:** $0 forever — the Python library (MIT), the Mac app, the Chrome extension, basic PII masking, and local semantic search.
- **Pro · Team:** $20/user/month — advanced masking and custom rules, audit log exports, team sharing, usage analytics, and priority support.
- **Enterprise:** custom — on-prem / VPC deployment, SSO/SAML, SOC 2 & HIPAA compliance, custom models, and SLAs. Contact us at omna.dev.

The first 10,000 users who sign up get Omna free during early access and lock in that free access. Claim your spot in the extension popup or at [omna.dev/pricing](https://omna.dev/pricing).

---

# 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/<subfolder>
```
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