Documentation

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 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 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.

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.

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.