Installation

Get Irrlicht running on your Mac in under two minutes via the package installer, or build everything from source.

Prerequisites

• macOS 13 (Ventura) or later — Irrlicht uses SwiftUI APIs that require Ventura as a minimum.
• Linux (daemon-only) — x86-64 or ARM64, Linux 5.3+ (for pidfd exit detection). The daemon runs headless with the web dashboard as its UI; there is no menu-bar app on Linux yet. See Linux setup below.
• At least one supported AI coding agent installed and working:
  • Claude Code
  • OpenAI Codex CLI
  • Pi
  • Aider
  • OpenCode

If you plan to build from source, you will also need:

• Go 1.21+ — the daemon is written in Go
• Swift 5.9+ — the menu-bar app is a native SwiftUI application
• Xcode Command Line Tools — install with xcode-select --install

Install via Homebrew (Recommended)

For Mac users with Homebrew, this is the simplest path. The cask points at the same Developer-ID signed + Apple-notarized DMG as the GitHub release, and lets brew upgrade handle future versions. Starting in v0.4.7 the app also auto-updates itself via Sparkle, so manual upgrades become optional.

brew tap ingo-eichhorst/irrlicht
brew install --cask irrlicht

To upgrade later:

brew upgrade --cask irrlicht

Install via curl

One command. No Gatekeeper prompts. The script downloads the Developer-ID signed and Apple-notarized app, verifies the SHA-256 checksum, and launches it.

curl -fsSL https://irrlicht.io/install.sh | sh

Options:

• --daemon-only — install just irrlichd to ~/.local/bin/ (no menu bar app)
• --version X.Y.Z — pin a specific version instead of latest

# Daemon only
curl -fsSL https://irrlicht.io/install.sh | sh -s -- --daemon-only

# Specific version
curl -fsSL https://irrlicht.io/install.sh | sh -s -- --version 0.3.4

Install via DMG / PKG

Manual drag-and-drop install. Use this if you prefer not to run a shell script, or if you're installing offline.

1. Download the DMG or PKG

   Grab Irrlicht-<version>.dmg or Irrlicht-<version>-mac-installer.pkg from the GitHub Releases page.

2. Install the app

   Open the DMG and drag Irrlicht.app to Applications. You may need to approve the app in System Settings → Privacy & Security if Gatekeeper blocks it.

3. What gets installed

   Component	Location
   Irrlicht.app (menu-bar app + embedded daemon)	/Applications/Irrlicht.app

   The daemon (irrlichd) is embedded inside the app bundle and managed automatically. No separate services or LaunchAgents needed.

4. Launch the app

   Open Irrlicht from Applications. A dimmed grey flame appears in the menu bar, and the daemon starts automatically in the background.

   On first launch the app also registers itself as a macOS login item (via SMAppService), so the menu-bar overlay is up before you open your first terminal after a reboot. Toggle this off in Preferences → "Start Irrlicht at login" if you prefer to launch the app manually; the choice is persisted and the default never re-applies.

Linux (daemon-only)

On Linux, Irrlicht ships as a headless daemon — the same irrlichd as on macOS, observing sessions via /proc and pidfd instead of lsof/kqueue. There is no tray app yet; the web dashboard at http://127.0.0.1:7837 is the UI. Session detection, states, costs, token metrics, and lifecycle all work; terminal-window focus is macOS-only and degrades cleanly to "unsupported."

The curl installer auto-detects Linux and installs the daemon only (it picks the right amd64/arm64 build):

curl -fsSL https://irrlicht.io/install.sh | sh

This installs irrlichd to ~/.local/bin/, the dashboard assets to ~/.local/share/irrlicht/web/, and a systemd user unit at ~/.config/systemd/user/irrlichd.service (written but not enabled). Start it directly with ~/.local/bin/irrlichd &, or enable the unit for autostart.

Autostart with systemd

The installer already wrote the unit, so just enable it:

systemctl --user enable --now irrlichd

If you built from source instead of using the installer, create the unit yourself (%h expands to your home directory):

mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/irrlichd.service <<'EOF'
[Unit]
Description=Irrlicht — AI coding-agent session monitor
Documentation=https://irrlicht.io/docs/installation.html

[Service]
ExecStart=%h/.local/bin/irrlichd
Restart=on-failure
RestartSec=2

[Install]
WantedBy=default.target
EOF

systemctl --user daemon-reload
systemctl --user enable --now irrlichd

On a headless server, allow the user service to keep running after you log out:

loginctl enable-linger "$USER"

Check it: systemctl --user status irrlichd, then open http://127.0.0.1:7837. The curl installer's --uninstall flag stops and removes the unit.

Build from Source

Building from source gives you the full installer package, identical to the release download.

One-command build

git clone https://github.com/ingo-eichhorst/Irrlicht.git
cd Irrlicht
./tools/build-release.sh

The script produces a .dmg (and optionally a .pkg) in the build directory.

What the build script does

Under the hood, build-release.sh performs these steps in order:

1. Syncs the web frontend — embeds the latest HTML/CSS/JS assets into the daemon binary.
2. Cross-compiles the daemon — builds irrlichd for both arm64 (Apple Silicon) and amd64 (Intel).
3. Creates a universal binary — merges both architectures with lipo so one binary runs natively on any Mac.
4. Builds the Swift menu-bar app — compiles Irrlicht.app from the SwiftUI source.
5. Embeds the daemon — places the universal irrlichd binary inside Irrlicht.app/Contents/MacOS/.
6. Packages into DMG and installer — creates a .dmg for drag-and-drop install and a .pkg installer.

Manual build (individual components)

If you prefer to build each component separately for development:

Daemon only

cd core && go build ./cmd/irrlichd/

Menu-bar app only

cd platforms/macos && swift build

Post-Installation

Once installed (via either method), Irrlicht is ready to go.

• The app manages everything — the embedded daemon starts automatically when the app launches. No separate services or LaunchAgents needed.
• The menu-bar app appears in your menu bar as a flame icon. Click it to see the current state of all detected AI agent sessions.

Verify the daemon is running

curl http://127.0.0.1:7837/state

A successful response returns a JSON object with the current global state. If the daemon is not running, verify the app is launched and check logs.

Check logs

Daemon logs are written to:

~/Library/Application Support/Irrlicht/logs/

Inspect these if the daemon fails to start or you encounter unexpected behaviour.

Uninstalling

To remove Irrlicht completely, quit the app and delete the following:

# Remove the app
rm -rf /Applications/Irrlicht.app

# Remove application data and logs
rm -rf ~/Library/Application\ Support/Irrlicht/