Configuration

Zero configuration by default. Environment variables for power users.

Philosophy

Irrlicht is designed to work with zero configuration. Install and run — sessions are discovered automatically. These options exist for power users who need to customize behavior.

Environment Variables

Variable Type Default Description
IRRLICHT_MAX_SESSION_AGE Duration 120h (5 days) Maximum age for transcript sessions before pruning
GT_BIN Path $PATH lookup Override path to Gas Town gt CLI binary
IRRLICHT_USE_FILES Boolean (1/0) unset Enable file polling mode in macOS app (legacy, not recommended)
IRRLICHT_DISABLED Boolean (1/0) unset Disable the daemon entirely (kill switch)

Filesystem Paths

Daemon

  • Session instances: ~/Library/Application Support/Irrlicht/instances/
  • Logs: ~/Library/Application Support/Irrlicht/logs/
  • Unix socket: ~/.local/share/irrlicht/irrlichd.sock

macOS App

  • Session order: ~/Library/Application Support/Irrlicht/session-order.json

Transcript Locations

  • Claude Code: ~/.claude/projects/<project>/<session-id>.jsonl
  • Codex: ~/.codex/sessions/YYYY/MM/DD/<session-id>.jsonl

App Settings

The macOS app has a Settings panel accessible via the gear icon:

Session TTL

  • Controls auto-deletion of idle ready sessions
  • Options: Never, 15 minutes, 30 minutes (default), 1 hour, 4 hours
  • Stored in @AppStorage("sessionTTLMinutes")

Notifications

  • Context pressure notifications at 80% and 95%
  • Requires macOS notification permission (requested on launch)

Logging

  • Format: Structured JSON
  • Location: ~/Library/Application Support/Irrlicht/logs/
  • Files: irrlicht.log (current), irrlicht.log.1 through .5 (rotated)
  • Max size: 10MB per file, 5 files retained
  • Log event types: startup, shutdown, session-detector, process-watcher, process-exit

Network

  • TCP: localhost:7837 (HTTP API + WebSocket + Web UI)
  • Unix socket: ~/.local/share/irrlicht/irrlichd.sock
  • mDNS: _irrlicht._tcp (Bonjour/Zeroconf discovery)

Daemon Lifecycle

The daemon (irrlichd) is embedded inside Irrlicht.app and managed automatically. When you launch the app, the daemon starts; when you quit, it stops. If the daemon crashes, the app restarts it with exponential backoff.

If an external daemon is already running (e.g. from a development build), the app detects it and uses the existing instance instead of spawning a new one.