---
title: Filters
description: Allow and deny lists that discard events before they are written — the privacy boundary of Tadoru.
---

Filters decide which apps and sites are recorded **at all**. They run in the Privacy Filter stage, before the store — excluded data is never written, so there is nothing to delete or leak later. This is the trust core of Tadoru.

## Two kinds of "filtering by app" — don't confuse them

| | **Capture-time filters** (this page) | **Query-time filters** (`--app` etc.) |
| --- | --- | --- |
| Where it acts | Before the store — matching events are **discarded** | Only when reading data back |
| Purpose | **Privacy boundary** — keep sensitive apps out of the store entirely | Convenience — narrowing results |
| Configured via | `tadoru filter` commands / `[filter]` in `config.toml` | Per-command flags like `--app`, `--types` |
| From MCP | **Cannot be changed** (read-only boundary) | Usable as `query_events` arguments |

## Managing the lists

```bash
tadoru filter show                                      # current lists and active mode
tadoru filter exclude-app add com.1password.1password   # deny list: add
tadoru filter exclude-app remove com.1password.1password
tadoru filter only-app add com.apple.Safari             # allow-only list: add
tadoru filter exclude-site add example.com              # exclude by URL host (browser.* events)
tadoru filter only-site add github.com
```

| Subcommand | `config.toml` key | Meaning |
| --- | --- | --- |
| `exclude-app` | `exclude_apps` | Deny list — everything else is captured |
| `only-app` | `include_only_apps` | Allow list — when non-empty, **only** listed apps are captured |
| `exclude-site` | `exclude_websites` | Deny list for `browser.*` URL hosts |
| `only-site` | `include_only_websites` | Allow list for `browser.*` URL hosts |

Editing `config.toml` directly is equivalent; the CLI additionally validates keys and deduplicates, so it's the safer path. The daemon watches the config file at roughly 2-second intervals, so changes apply within a few seconds — **no daemon restart needed**.

:::warning[Allow-list mode is a mode switch]
Adding even one entry with `only-app` switches app capture to allow-list mode: only listed apps are recorded. `tadoru filter show` always displays which mode is active.
:::

## Matching semantics

- **Apps** — match by `bundle_id` (recommended; display names can change or be spoofed). An app that has a `bundle_id` is matched **only** by it; a display-name entry applies only to events whose app has no `bundle_id`. Matching is case-insensitive.
- **Sites** — dot-boundary suffix match on the URL host: `example.com` also covers `api.example.com`, but not `evil-example.com`. There is no Public Suffix List handling — an entry like `com` matches every `.com` host, so prefer full domain names. Site rules apply to the URL host of `browser.*` events, so you can keep recording the browser while dropping specific sites.
- **Precedence** — if `include_only_*` is non-empty, an event is captured only if it is **in that list and not in `exclude_*`**. If empty, everything not excluded is captured.
- **App-level exclusion is total** — it drops **all** event types from that app (`ui.*`, `input.*`, `window.*`, ...), not just some.

## Always-on exclusions

Independent of your lists:

- **Private browsing is always excluded** (Chrome Incognito, detected deterministically).
- **Built-in exclusions are always applied** — password managers and credential stores (`1Password`, `Keychain Access`, ...) are excluded by a hard-coded layer that cannot be lifted, not even with `include_only_apps`. It is a separate layer from the default entries you see in `exclude_apps` in `config.toml` — editing those does not affect it. `filter show` lists the built-in entries separately from your own.

## Filters and MCP

Capture-time filters **cannot be modified over MCP** — the MCP server is a read-only view by design. An agent can never weaken your privacy boundary, even by accident. Filter management happens only through the CLI or `config.toml`. See [MCP server](/reference/mcp).