Quick Start

Get up and running with Irrlicht in minutes. Follow these steps to monitor your first AI coding session.

Prerequisites: macOS with Irrlicht installed and running (see Installation), and at least one supported coding agent.

Your First Session

  1. Install Irrlicht
    Follow the installation guide to get Irrlicht.app on your system.
  2. Launch the app
    open /Applications/Irrlicht.app

    The embedded daemon (irrlichd, the background process that watches your sessions) starts automatically — no separate services to manage.

  3. Look for the flame icon
    A small flame appears in your macOS menu bar — dimmed grey when no sessions are active — confirming Irrlicht is running.
  4. Start an AI coding session
    Open a terminal and launch any supported agent (Claude Code, Codex, Pi, Aider, OpenCode, Kiro CLI, Gemini CLI, Antigravity, Mistral Vibe, GitHub Copilot, Hermes Agent, Muse, Junie, or DeepSeek Harness) as you normally would.
  5. Watch the menu bar
    A purple dot appears as the agent starts working. The light changes color to reflect the agent's state in real time.
  6. Click the menu bar icon
    The popover shows full session details including model, tokens, cost, and context pressure.

What You'll See

  • Project name, git branch, model, elapsed time, and token count
  • Context utilization percentage with pressure-level colors
  • Estimated cost per session
  • Sessions grouped by project

Understanding the States

  • working -- the agent is processing
  • waiting -- the agent needs your input
  • ready -- the agent is idle
  • error -- the session's own machinery failed (the provider refused the call, credentials were rejected). Not a failing build or an empty grep -- those are the agent working normally.
Tip Each state maps to one menu bar light color. Learn more in The Light System.

Web Dashboard beta

Open http://127.0.0.1:7837 in your browser for the web UI. It provides the same session data as the menu bar app, with real-time updates via WebSocket. The web dashboard is in beta — it tracks the menu-bar app's layout but a few macOS-only features (click-to-jump, system-level notifications with custom sounds, debug action buttons) don't have a web equivalent.

CLI Listing

For a terminal-based view of all active sessions:

irrlicht-ls

Use watch mode for a live-updating display that refreshes every second:

irrlicht-ls -w

Next Steps