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 and the daemon via Homebrew. One tap, two formulae, 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 purple, amber, and green map to working, waiting, and ready. The core visual language of Irrlicht.
State Machine
The three states, their transitions, and how filesystem events drive the session lifecycle.
Session Detection
How Irrlicht discovers agent sessions through filesystem watching, JSONL parsing, and lock files.
Configuration
Notification thresholds, polling intervals, and display preferences. Most users need zero changes.
CLI Tools
The irrlichtctl 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.
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.