CLI Tools

Command-line utilities for interacting with Irrlicht.

irrlichd

The background daemon that powers Irrlicht.

Usage

irrlichd [flags]

Flags

  • --version, -v — Print version and exit
  • --diagnose — Write a redacted diagnostics bundle (irrlicht-diag.tar.gz) to the current directory and exit, without starting the daemon. For headless installs that can't reach the GET /debug/bundle endpoint. Honors IRRLICHT_HOME
  • --uninstall-hooks — Remove irrlicht's Claude Code hooks from ~/.claude/settings.json, record the hooks permission as denied if it was previously granted (so it isn't silently re-installed on next start), and exit without starting the daemon
  • --uninstall-task-eta — Remove irrlicht's managed task-eta and task-summary blocks from ~/.claude/CLAUDE.md and exit without starting the daemon
  • --record — Enable lifecycle recording of session events to <dataDir>/recordings (equivalent to IRRLICHT_RECORD=1); the daemon starts normally otherwise

Flag Examples

# Print version and exit
irrlichd --version

# Write a diagnostics bundle to the current directory
irrlichd --diagnose

# Start with lifecycle recording enabled
irrlichd --record

What It Does

  • Watches Claude Code, Codex, Pi, Aider, Kiro CLI, Antigravity, and Mistral Vibe transcripts; OpenCode's SQLite WAL; Gemini CLI's transcripts; plus the Gas Town orchestrator (a multi-agent coordinator layer distinct from the per-agent adapters above)
  • Tracks session state via deterministic state machine
  • Serves HTTP API on localhost:7837
  • Serves WebSocket stream for real-time updates
  • Advertises via mDNS (_irrlicht._tcp)
  • Listens on Unix socket at ~/.local/share/irrlicht/irrlichd.sock

Health Check

curl http://127.0.0.1:7837/state

Logs

tail -f ~/Library/Application\ Support/Irrlicht/logs/events.log

irrlicht-ls

A terminal session listing tool.

Usage

irrlicht-ls [flags]

Flags

  • -w, --watch — Watch mode — updates every second (clears screen between refreshes)
  • --format text|json — Output format; json emits the same grouped tree as GET /api/v1/sessions (minus cost aggregation)
  • --yield — Append two columns after the cost: the yield state and the session's HEAD commit (7 chars)
  • --id <prefix> — Filter by session ID prefix (case-insensitive)
  • --state working|waiting|ready — Filter by session state
  • --project <substring> — Filter by project name (case-insensitive substring)
  • --adapter <name> — Filter by agent adapter (the per-agent integration, e.g. claude-code, codex)

Flag Examples

# Watch mode, refreshing every second
irrlicht-ls -w

# Only waiting Claude Code sessions, as JSON
irrlicht-ls --state waiting --adapter claude-code --format json

Output Format

Columns: state, project name, session ID (8 chars), model, context utilization (percent, color-coded by pressure level on a TTY; set NO_COLOR to disable) with context window, cost (USD), adapter, subagent badge, age. Child sessions are indented below their parent. When sessions span multiple projects, each project gets a header line with its session count. waiting sessions show the assistant's last message beneath the row; sessions with a task list show N/M completed.

Example output:

irrlicht (5 sessions)
working  irrlicht     52d087d1 claude-opus-4-6 47% 1000k $3.21 claude-code [3 agents: 3w/0r]  (2s ago)
  working  irrlicht     agent-a1 claude-haiku-4-5 8% 200k $0.04 claude-code  (5s ago)
  working  irrlicht     agent-a4 claude-haiku-4-5 6% 200k $0.03 claude-code  (8s ago)
  working  irrlicht     agent-ab claude-haiku-4-5 5% 200k $0.02 claude-code  (6s ago)
waiting  irrlicht     99887766 claude-opus-4-6 92% 1000k $7.80 claude-code  (12s ago)
    ? Should I delete the legacy migration before running the suite?
    2/5 completed

api-server (1 session)
ready    api-server   e5f6g7h8 gpt-5 3% 400k codex  (1m ago)

Data Source

Reads session JSON files from ~/Library/Application Support/Irrlicht/instances/ and builds the same hierarchical dashboard as the API. Works independently of the daemon.

Installation

irrlicht-ls ships inside Irrlicht.app and lands on your PATH automatically: the PKG installer and the curl … | sh installer symlink it to /usr/local/bin/irrlicht-ls. If you installed by dragging the DMG, open the menu bar panel → Settings → Install Command-Line Tool. Building from source (from the repo root): cd core && go build ./cmd/irrlicht-ls/.

irrlicht-focus

Brings the terminal/IDE window for a session to the foreground.

Usage

irrlicht-focus <sessionID>

Example

irrlicht-focus 52d087d1

Brings the terminal/IDE window for session 52d087d1 (see irrlicht-ls above for session IDs) to the foreground; exits 0 on success.

Arguments

  • <sessionID> — The session ID to focus (required positional argument; no flags)

What It Does

  • POSTs to the daemon's POST /api/v1/sessions/{id}/focus endpoint on http://127.0.0.1:7837
  • The daemon broadcasts a focus_requested WebSocket message; the macOS menu-bar app receives it and activates the window

Exit Codes

  • 0 — Success
  • 1 — Usage error or daemon unreachable
  • 2 — Session not found or has no launcher data

irrlichtrelay

The standalone relay server. Daemons push their session events to it over a WebSocket, and it fans them out to connected macOS/web clients while re-serving the dashboard and the daemon's HTTP API (/api/v1/sessions, /api/v1/agents, /api/v1/version) from an in-memory cache.

Usage

irrlichtrelay [serve] [flags]
irrlichtrelay token issue|list|revoke [flags]
irrlichtrelay --version

The default subcommand is serve (used when the first argument is a flag or absent); it runs the relay until SIGINT/SIGTERM. The token subcommand manages the hashed bearer-token store used by --auth tokens-file.

serve Flags

  • --addr — TCP address to listen on (default 127.0.0.1:7839; pass 0.0.0.0:7839 to expose on the LAN, and only with --auth or behind a TLS-terminating proxy)
  • --tls-cert — PEM certificate file for native TLS (wss://); pair with --tls-key (default empty)
  • --tls-key — PEM private-key file for native TLS (wss://); pair with --tls-cert (default empty)
  • --auth — Authentication mode: off (trusted LAN, accept any hello) or tokens-file[:PATH] (verify a hashed bearer token; PATH defaults to <data-dir>/tokens.json) (default off)
  • --origin-allowlist — Comma-separated Origin hosts allowed for browser WS clients (empty = allow all, loopback-safe) (default empty)
  • --data-dir — State directory for the tokens file (default empty → $IRRLICHT_HOME or ~/.local/share/irrlicht)
  • --max-msg-bytes — Max inbound WebSocket message size in bytes; 0 disables (default 1048576)
  • --max-conns — Max total concurrent connections; 0 disables (default 256)
  • --max-conns-per-ip — Max concurrent connections per remote IP; 0 disables (meaningless behind a proxy/NAT — see --max-conns) (default 32)
  • --version, -v — Print version and exit

serve Flag Examples

# Listen on the LAN with a bearer-token allowlist and native TLS
irrlichtrelay serve --addr 0.0.0.0:7839 --auth tokens-file \
  --tls-cert /etc/irrlicht/relay.pem --tls-key /etc/irrlicht/relay.key

# Cap message size and per-IP connections on a shared box
irrlichtrelay serve --max-msg-bytes 524288 --max-conns-per-ip 8

token Flags

  • --tokens-file — Path to the tokens file (default empty → <data-dir>/tokens.json)
  • --data-dir — State directory for the tokens file (default empty → $IRRLICHT_HOME or ~/.local/share/irrlicht)
  • --label — Human label for the issued token (issue only)
  • --workspace — Tenant workspace the issued token is scoped to (issue only; empty means the default single-tenant workspace)

Example:

irrlichtrelay token issue --label "laptop" --workspace default

Security Note

The relay binds loopback by default. A non-loopback bind without --auth is wide open regardless of TLS — TLS encrypts the wire but does not authenticate the peer, so anyone who can reach the address can read every session and inject as a daemon. Enable --auth or restrict access at the network layer when exposing it.

Building CLI Tools

cd core
go build ./cmd/irrlichd/        # daemon
go build ./cmd/irrlicht-ls/     # listing tool
go build ./cmd/irrlicht-focus/  # focus a session's window
go build ./cmd/irrlichtrelay/   # standalone relay server

Or use the release build script:

./tools/build-release.sh
Previous macOS Setup Next API Reference