macOS Setup

A few system settings to make Irrlicht work at its best — especially when you spend most of your time in full-screen apps.

Prerequisites: macOS 13 (Ventura) or later with Irrlicht installed (see Installation).

The Permission Wizard (First Run)

Irrlicht is consent-first: it monitors nothing until you say so. On first launch — and again after an upgrade adds new permissions — it detects which coding agents are running and shows a permission wizard listing every read and modification it wants to make, per agent: transcript tailing, hook installs, statusline wraps, database polling. Nothing is read or installed until you hit Apply.

The wizard appears on whichever surface you're looking at — the macOS popover or the web dashboard — and the first answer wins. You can revisit every decision later under Settings → Permissions → Review; toggling a permission off actively undoes it (hooks uninstall, watchers stop). While permissions are unanswered, monitoring for that agent is paused — if Irrlicht looks idle right after an upgrade, answer the wizard.

Status Line in Full Screen

By default, macOS hides the menu bar whenever an app goes full screen. That means the Irrlicht flame — your live indicator of every agent's state — disappears exactly when you're heads-down in a terminal or editor.

Fix it in one step:

1. Open System Settings → Control Center.
2. Find "Automatically hide and show the menu bar" and set it to Never.

The menu bar — and the Irrlicht dot — will now stay visible on every Space, including full-screen ones.

Irrlicht's popover panel is already configured to appear on any Space (including full-screen Spaces). Once the menu bar is visible, clicking the flame opens the session list wherever you are.

Open at Login

Irrlicht registers itself as a login item on first launch and the setting is on by default, so it is running before you open your first terminal each day. To confirm it, or to turn it off:

1. Click the flame icon in the menu bar to open the session list.
2. Click the gear icon to open Settings.
3. Check Open at Login — it is on by default, and Irrlicht will start automatically at each login. Toggle it off if you would rather launch the app yourself.

Irrlicht registers itself via SMAppService so macOS manages the lifecycle — it starts early in the login sequence, before most apps open.

Notification Permissions

Irrlicht can alert you when an agent transitions to waiting (needs input) or ready (done). On first launch the system asks for permission.

If you denied the prompt and want to re-enable notifications:

1. Open System Settings → Notifications.
2. Find Irrlicht in the list.
3. Enable Allow Notifications and choose your preferred alert style.

Notification thresholds (which transitions trigger an alert) are configurable inside Irrlicht's own Settings panel.

Accessibility Permission (Window Focus)

Clicking a session row in the popover raises the terminal window that owns that session. This uses the macOS Accessibility API, which requires a one-time grant:

1. Open System Settings → Privacy & Security → Accessibility.
2. Enable the toggle next to Irrlicht.

Without this permission the click still works for some terminals but silently fails for others. Grant it once and clicks are always reliable.

Kitty Terminal — Precise Tab Focus

Most terminals work out of the box. Kitty needs one extra line so Irrlicht can target the exact tab (not just the window):

Add to ~/.config/kitty/kitty.conf:

allow_remote_control yes
listen_on unix:/tmp/kitty-{kitty_pid}