Installation

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

Prerequisites

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

  • Go 1.25+ — 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.5.1

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
    ComponentLocation
    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 Settings → "Open 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
Tip For distribution, always use build-release.sh which embeds the daemon into the app bundle. Manual builds are useful for development but require running the daemon separately.

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.

Note The daemon listens on 127.0.0.1:7837 by default. This port is not exposed to the network. See the Configuration page to change the bind address or port.
Consent first Irrlicht monitors nothing out of the box. On first launch it detects which coding agents are running and shows a permission wizard — on the macOS app or the web dashboard, whichever you're looking at — listing every read and modification it wants to make, per agent. Nothing is read or installed until you hit Apply, and revoking a permission later actively undoes it (hooks uninstall, watchers stop).
Restart Claude Code after granting the statusline permission When you grant Claude Code's statusline permission, Irrlicht registers a statusLine.command entry in ~/.claude/settings.json. Any Claude Code session already running at that point won't pick it up — close and reopen it once to activate the integration.

Uninstalling

Use the installer's --uninstall flag. It stops the daemon, removes the app bundle, the irrlichd binary and the LaunchAgent (or systemd user unit on Linux), and clears the hook entries Irrlicht wrote into your agent configs:

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

Your session history and configuration in ~/Library/Application Support/Irrlicht/ are kept. To remove those too:

rm -rf ~/Library/Application\ Support/Irrlicht/
Warning Removing the Application Support/Irrlicht/ directory deletes all local session history and configuration. Back up anything you want to keep before running the command above.
Deleting the app by hand leaves hooks behind If you remove Irrlicht by dragging it to the Trash or with rm -rf /Applications/Irrlicht.app, the hook entries stay in your agent configs and keep firing at a port nothing is listening on. Run --uninstall above instead — or, if the binary is already gone, clear Irrlicht's entries from ~/.claude/settings.json and ~/.codex/hooks.json yourself.
Previous Overview Next Quick Start