🟣 working · 🟠 waiting · 🟢 ready — one ambient dot per session, multi-agent, no hooks.
Homebrew (recommended):
brew tap ingo-eichhorst/irrlicht
brew install --cask irrlichtcurl:
curl -fsSL https://irrlicht.io/install.sh | shDMG: download Irrlicht-<version>.dmg from Releases and drag Irrlicht.app to Applications.
→ Quickstart gets you to your first purple dot in 60 seconds.
- Three-state menu-bar dot per session — 🟣 working, 🟠 waiting, 🟢 ready
- Context-pressure gauge — 🟢 → 🟡 → 🔴 →
⚠️ before the auto-compact cliff, so you can/compactwhile quality is still intact - Live per-session cost in USD — model-aware via LiteLLM pricing
- Subagent trees — parent ↔ Explore / Plan / background agents, not just the parent
- Git-aware grouping — sessions clustered by project, branch, worktree
- Real-time — <1s latency via FSEvents/kqueue; no polling
Stages: stable production-ready · beta feature-complete, edge cases remain · alpha core detection works, rough edges · planned on the roadmap.
Coding agents
| Agent | Stage |
|---|---|
| Claude Code | beta |
| OpenAI Codex | alpha |
| Pi | alpha |
| Aider | alpha |
| OpenCode | alpha |
| Gemini CLI | planned |
| Cursor Agent | planned |
| Amp | planned |
Orchestrators
| Orchestrator | Stage |
|---|---|
| Gas Town | alpha |
| Claude Squad | planned |
| Custom (plugin API) | planned |
Platforms
| Platform | Stage | Access |
|---|---|---|
| macOS (menu bar app) | beta | Releases |
| Web dashboard | beta | http://127.0.0.1:7837 |
| CLI | alpha | irrlicht-ls (-w for watch) |
| VS Code extension | planned | tracked in #350 |
| Linux | planned | — |
| Windows | planned | — |
→ Adapters reference for stage criteria, watch paths, model detection, and roadmap.
Local-first · no telemetry · MIT · ~5 MB RAM · signed Homebrew cask · transcripts read-only.
- Quota & cost trackers (ccusage, codeburn, ClaudeBar, SessionWatcher) count tokens and dollars, not state.
- Observability stacks (Langfuse, SigNoz) need SDK instrumentation and a dashboard tab.
- Single-agent monitors (Claude Status, Agent Sessions) lock you to one CLI or one terminal.
Irrlicht is ambient (menu bar, not a window), multi-agent (Claude / Codex / Pi / Aider / OpenCode / Gas Town in one vocabulary), and transcript-driven — no SDK wrappers, no OpenTelemetry collectors, no dashboard tab to keep open.
In Goethe's Faust, an Irrlicht guides the way through the night. This one guides you through your agents — who's working, who's waiting, and where you're needed next.
Six concrete pains, every one documented:
- You don't know which session needs you. Claude Code's desktop notifications don't fire inside tmux — the most common multi-session setup.
- Parallel sessions shred your attention. "The mental gymnastics of context switching wears me out and makes me wonder how well I'm steering each session" (dev.to).
- Context compaction silently wrecks quality. Auto-compact fires at ~80% of the window, but the model degrades 20–30% before that (MindStudio; GitHub issue with hundreds of reactions).
- Cost runs away in the dark. A recent prompt-caching bug silently inflated token usage 10–20× for weeks (The Register) — visible only on the invoice.
- Subagents are a black box. Spawn three Explore agents and a background task; you see the parent, not each child.
- Quota makes you agent-hop — and monitoring doesn't follow. Burn Claude Code by 11am, fall back to Codex or Gemini; each agent has its own vocabulary for "working", "waiting", and "done".
(Irrlicht is German for will-o'-the-wisp — a light that guides you through the dark.)
Transcript files → FSEvents/kqueue → state machine → menu bar
Irrlicht reads the .jsonl transcripts your agents already write, persists each session as atomic JSON under ~/Library/Application Support/Irrlicht/instances/, and renders dots in a SwiftUI menu-bar app over a local WebSocket. The app ships as a single .app bundle with the daemon embedded — no separate services, no version drift.
→ Architecture for the hexagonal pipeline and state-machine rules.
Irrlicht is agent-verifiable by design — every session lives as atomic JSON at a known path, so any tool (including the coding agents themselves) can read live state and verify its own work.
- State files:
~/Library/Application Support/Irrlicht/instances/*.json - Conventions and test gate: AGENTS.md
Documentation · Installation · Changelog · Issues · Discussions
MIT License — see LICENSE.