CLI Tools

Command-line utilities for interacting with Irrlicht.

irrlichd

The background daemon that powers Irrlicht.

Usage

irrlichd [flags]

Flags

• --version — Print version and exit

What It Does

• Watches Claude Code and Codex transcript directories
• 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/irrlicht.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 json — Output the full DashboardResponse as JSON
• --id <prefix> — Filter sessions by ID prefix

Output Format

Columns: state, project name, session ID (8 chars), model, context window, subagent badge, age. Child sessions are indented below their parent.

Example output:

working  irrlicht     52d087d1 claude-opus-4-6 1000k [3 agents: 3w/0r]  (2s ago)
  working  irrlicht     agent-a1 claude-haiku-4-5 200k  (5s ago)
  working  irrlicht     agent-a4 claude-haiku-4-5 200k  (8s ago)
  working  irrlicht     agent-ab claude-haiku-4-5 200k  (6s ago)
ready    api-server   e5f6g7h8 claude-opus-4-6 1000k  (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.

Building CLI Tools

cd core
go build ./cmd/irrlichd/     # daemon
go build ./cmd/irrlicht-ls/  # listing tool

Or use the release build script:

./platforms/build-release.sh