# Notifications (/docs/haus/rooms/notifications)



Every banner this desktop draws goes through `haus-notify`: to
**[trill](/docs/trill)** when trill answers on its socket, to Apple's banner when
nothing does. That runs on every haus machine, so no room waits on trill being
installed. This one asks only: **does haus own the bundle?**

## Enable it [#enable-it]

```nix
haus.notifications.compositor = true;
```

```sh
haus rebuild
```

Off by default. There is no `haus.notifications.enable`: `false` would claim this
Mac draws no haus notifications, which is never true. On, the room installs
Trill.app at `/Applications/Trill.app`, pinned by your `flake.lock` like every
other room, and puts trill's [agent skill](/docs/haus/rooms/ai) beside haus's.
Back to `false`, it stops installing and updating trill and deletes nothing.

It does not decide what happens to any one notification: that is
`~/.config/trill/rules.json`, reloaded on save, and haus adds no second dial.
Every `haus-notify` send carries a `--source` (`haus.bar`, `haus.lane`, one per
room), so "stop telling me about the bar reloading" is a line there, not a
rebuild.

## New mail [#new-mail]

`haus.mail` holds an IMAP connection open with IDLE, so nothing polls: a card
lands a second or two behind the mail, drawn by `haus-notify` like every other
card.

```nix
haus.mail = {
  enable = true;
  address = "you@gmail.com";
  mailboxes = [ "INBOX" ];
};
```

`INBOX` is the one name IMAP standardises; the rest are your provider's spelling,
and Gmail's are bracketed (`[Gmail]/Starred`). haus refuses an empty list: it
would watch every mailbox on the account, so on Gmail one message arrives once
per label.

Then the password, once:

```sh
haus rebuild
haus-secret --check
```

`--check` asks for `MAIL_IMAP_PASSWORD` and keeps it wherever
[`haus.secrets.provider`](/docs/haus/rooms/security#secrets-your-rooms-need)
points, your login keychain by default. Google wants an [app
password](https://myaccount.google.com/apppasswords) here, not your account
password, and minting one needs 2-Step Verification. There is no OAuth: Google
expires an unverified app's refresh token weekly.

<Callout type="warn" title="An app password reads the whole mailbox">
  It is static, so it belongs in the keychain, never your host file. Revoking it on
  Google's page cuts this Mac off, and no other machine of yours notices.
</Callout>

Until there is a password the watcher parks and says so in
`~/Library/Logs/haus-mail.log`.

### What counts as new [#what-counts-as-new]

A mailbox nobody has watched records where it is, so turning this on draws no
card for what is already unread. After that a message must be unseen and newer
than the last this Mac announced, so your laptop stays quiet about mail you read
on your phone at breakfast.

More than five at once collapses into one card saying how many. On Gmail a card
carries an Open pill to the message's thread; elsewhere none. The mailbox is
opened read-only, headers only: nothing marks your mail as read, and no card
carries a preview.

## Options [#options]

[Every setting, with types and
defaults](/docs/haus/reference/options#notifications).