The Light System

Three states. No ambiguity. Each session is a single light whose color tells the truth.

Philosophy

The name Irrlicht comes from the folklore of the Harz, the ancient mountain range in central Germany. An Irrlicht is a will-o'-the-wisp — a ghostly light that drifts over the moors and bogs near the Brocken, luring wanderers off the safe path and into the marsh. Harzer miners reported phantom lights in the tunnels near Clausthal-Zellerfeld — sometimes a warning, sometimes a promise of ore ahead.

The most famous Irrlicht appears in Goethe's Faust. On Walpurgis Night, an Irrlicht guides Faust and Mephistopheles up the Brocken, lighting their way through the Traum- und Zaubersphäre — the realm of dream and sorcery. A treacherous companion on a treacherous path.

This Irrlicht flips the myth. Instead of a deceptive light that leads you astray, it is the tamed will-o'-the-wisp — small, honest lights that appear exactly where your attention should go. You run four Claude sessions across three projects. Without Irrlicht, you tab between terminals, guess which agent is stuck, and interrupt work that was humming along fine. With Irrlicht, a glance at the menu bar tells you everything: which sessions are thinking, which need you, and which are done.

The core promise No ghosts. Files → State → Light. The light system is deterministic — given the same transcript, every run produces the same state.

The Three States

Irrlicht's state model is MECE — mutually exclusive, collectively exhaustive. Every session is in exactly one state at any given moment. There is no fourth state, no "unknown", no "cancelled". Three states, three colors, three meanings.

working

The agent is actively processing. This includes text generation, tool calls, shell commands, hooks, compaction, and API retries. The session is busy and does not need your attention.

  • Text is being streamed to the terminal
  • A tool call is executing (file writes, grep, bash)
  • The context window is being compacted
  • An API request is in flight or being retried
Leave it alone A purple light means the agent is doing its job. Switching to this terminal and typing will only interrupt its flow.

waiting

A user-blocking tool is open — the agent has stopped and needs your judgment before it can continue. The story pauses until you respond.

Only two tools trigger the waiting state:

  • AskUserQuestion — the agent is asking you a clarifying question
  • ExitPlanMode — the agent wants to leave plan mode and start executing
This one needs you An orange light is the only state that demands your attention. Switch to this terminal and answer the question.

ready

The agent is idle at the prompt, waiting for your next instruction. The turn is complete — either the agent finished its work, the process exited, or a task was cancelled. The session is available for new work.

  • The agent completed its response and is showing the prompt
  • The agent process exited (gracefully or otherwise)
  • You cancelled a running task with ESC — the agent is back at the prompt
  • The session has been idle beyond the grace period
No "cancelled" state Cancellation is not a separate state. When you press ESC, the agent returns to the prompt — that is ready. Three states only: working, waiting, ready.

Decision Tree

The state machine evaluates each transcript update with a simple three-step decision:

  1. Is there an open user-blocking tool?
    If the last tool result is pending and the tool is AskUserQuestion or ExitPlanMode, the state is waiting.
  2. Is the agent actively processing?
    If there are recent transcript events indicating generation, tool execution, or API activity, the state is working.
  3. Otherwise
    The state is ready. The agent is idle and the session is available.
transcript update | v +---------------------+ | user-blocking tool? |--yes--> waiting (orange) +---------------------+ | no v +---------------------+ | active processing? |--yes--> working (purple) +---------------------+ | no v ready (green)

Context Pressure

Context pressure is orthogonal to the three states. It measures how full the agent's context window is and overlays a second dimension onto whatever state the session is in. A session can be working at any pressure level.

Level Utilization Color Meaning
safe 0 – 70% green Plenty of room. No action needed.
caution 70 – 85% yellow Context is filling up. Be aware.
warning 85% – 155K tokens red Running low. Consider wrapping up or starting a new session.
critical 155K+ tokens crimson Auto-compaction imminent. Finish the current task.

Irrlicht sends macOS notifications at two thresholds:

  • 80% utilization — a heads-up that context is getting heavy
  • 95% utilization — urgent warning before auto-compaction kicks in
Pressure is not state A session at critical pressure can still be working, waiting, or ready. The two dimensions are independent.

Cost Estimation

Irrlicht estimates per-session cost by combining model pricing with the token breakdown from each transcript. Input tokens, output tokens, and cache reads are tracked separately and priced according to the model being used (e.g., Opus, Sonnet, Haiku).

  • Per-session cost — computed from the cumulative token counts and the model's pricing tiers, displayed in the session detail view
  • Per-project aggregation — all sessions belonging to the same project are summed in the UI, giving you a running total for the project's spend

Costs are estimates based on published API pricing. Actual billing may differ due to caching, batching, or pricing changes.

Menu Bar Rendering

Sessions appear in the macOS menu bar as a row of colored dots. Each dot is one session, its color reflecting the current state. Projects are grouped together so related sessions sit side by side.

Sessions Display
0 A single white sparkle — clean slate, no active sessions
1 – 5 One colored dot per session, grouped by project
6 All six dots shown, menu bar getting full
7+ First 5 dots shown, then an ellipsis indicating overflow

The menu bar is designed to be glanceable. You should never need to open the dropdown to answer the question "does anything need me right now?" — if you see an orange dot, the answer is yes.

Previous Quick Start Next State Machine