Documentation
Irrlicht is a macOS menu bar app that monitors AI coding agent sessions in real time. These docs cover everything from installation to architecture, so you can get the most out of every light in your menu bar.
Installation
Install the menu bar app (with the daemon embedded) via Homebrew. One tap, one cask, zero config.
Quick Start
From install to first session in under two minutes. Launch an agent and watch the light change.
The Story
How Irrlicht came to be — from one agent and a broken movie night to a control plane for a coding factory.
The Light System
How each light color maps to a session state — purple, amber, green, red. The core visual language of Irrlicht.
State Machine
The session states, their transitions, and how filesystem events drive the session lifecycle.
Session Detection
How Irrlicht discovers agent sessions through filesystem watching, JSONL parsing, and process exit monitoring.
CO2 Methodology
How the CO2e estimate is calculated, the everyday equivalents shown on the History tab, and the studies behind every coefficient.
Configuration
Notification thresholds, polling intervals, and display preferences. Most users need zero changes.
macOS Setup
Keep the status dot visible in full screen, enable login autostart, and grant the permissions Irrlicht needs.
Phone Notifications
Pair a phone with Irrlicht Elfdans so a banner reaches you when an agent needs input or finishes — what it takes to host a relay, and what actually buzzes.
Tips & Tricks
Easy-to-miss settings that pay off: menu bar icon styles, quota forecasts, spoken alerts, click-to-jump, and usage exports.
CLI Tools
The irrlicht-ls command for querying sessions, debugging adapters, and inspecting state.
API Reference
IPC messages, session data structures, and event types for building integrations and custom adapters.
System Design
Daemon and app architecture, IPC protocol, and how the monitoring pipeline flows from filesystem to menu bar.
Adapters
Per-agent adapters for Claude Code, Codex, and others. How to write a custom adapter for any agent.
Claude Surfaces & Support
Which Claude interfaces and execution places Irrlicht can monitor. One row per product mode, with the evidence behind each answer.
Contributing
How to report bugs, suggest features, submit pull requests, and set up the development environment.
Code of Conduct
Community standards and expectations for respectful, inclusive participation in the project.
Changelog
Version history, release notes, breaking changes, and migration guides for every release.