API Reference

HTTP and WebSocket API served by irrlichd on localhost:7837.

Base URL

• HTTP: http://127.0.0.1:7837
• Unix socket: ~/.local/share/irrlicht/irrlichd.sock

Endpoints

GET /api/v1/sessions

Returns a hierarchical DashboardResponse with sessions grouped by project and nested parent-child relationships.

{
  "groups": [
    {
      "name": "irrlicht",
      "agents": [
        {
          "session_id": "52d087d1-...",
          "state": "working",
          "adapter": "claude-code",
          "project_name": "irrlicht",
          "pid": 12345,
          "subagents": { "total": 3, "working": 2, "waiting": 0, "ready": 1 },
          "children": [
            {
              "session_id": "agent-a1cad...",
              "state": "working",
              "parent_session_id": "52d087d1-...",
              "metrics": { "model_name": "claude-haiku-4-5", ... }
            }
          ],
          "metrics": {
            "model_name": "claude-opus-4-6",
            "context_utilization_percentage": 12.5,
            "pressure_level": "safe",
            "estimated_cost_usd": 0.18
          }
        }
      ]
    }
  ]
}

GET /state

Human-readable state summary. Shows count of working, waiting, and ready sessions, plus the total session count.

GET /api/v1/sessions/stream

WebSocket upgrade endpoint for real-time session state updates.

Message Types

Type	Description
session_created	New session detected
session_updated	Session state or metrics changed
session_deleted	Session removed
orchestrator_state	Orchestrator state snapshot

Message Format

{
  "type": "session_updated",
  "session": { ... SessionState ... }
}

GET /api/v1/orchestrators/{name}

Get orchestrator state by name (e.g. "gastown").

GET /api/v1/gastown

Backward-compatible endpoint for the Gas Town orchestrator state.

GET /

Serves the embedded web dashboard UI.

SessionState Schema

Field	Type	Description
session_id	string	Unique session identifier (UUID or proc-<pid>)
state	string	working, waiting, or ready
adapter	string	claude-code or codex
compaction_state	string	Current compaction state, if any
cwd	string	Working directory of the session
transcript_path	string	Absolute path to the JSONL transcript file
git_branch	string	Current git branch name
project_name	string	Project name derived from git root
pid	int	Process ID of the agent
first_seen	int64	Unix timestamp when the session was first detected
updated_at	int64	Unix timestamp of the last state update
metrics	object	SessionMetrics object (see below)
parent_session_id	string	ID of the parent session, if this is a sub-agent
subagents	object	SubagentSummary — aggregate state of all child sessions (see below)
daemon_version	string	Version of the running daemon

SubagentSummary Schema

Present on parent sessions that have active or recently-active child sessions (subagents). Computed by BuildDashboard by merging in-process agents (open Agent tool calls) with file-based child sessions.

Field	Type	Description
total	int	Total number of child sessions (in-process + file-based)
working	int	Count of children in working state
waiting	int	Count of children in waiting state
ready	int	Count of children in ready state

SessionMetrics Schema

Field	Type	Description
elapsed_seconds	int	Seconds since session started
total_tokens	int64	Total tokens consumed (input + output)
model_name	string	Normalized model name
context_window	int64	Total context window size for the model
context_utilization_percentage	float64	Percentage of context window used
pressure_level	string	Context pressure level (safe, moderate, high, critical)
has_open_tool_call	bool	Whether the agent has an open tool call
open_tool_call_count	int	Number of currently open tool calls
last_event_type	string	Type of the most recent transcript event
last_open_tool_names	[]string	Names of currently open tools
last_tool_result_was_error	bool	Whether the last tool result was an error
estimated_cost_usd	float64	Estimated session cost in USD

WebSocket Client Example

const ws = new WebSocket('ws://127.0.0.1:7837/api/v1/sessions/stream');
ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  console.log(msg.type, msg.session?.session_id);
};

curl Examples

# List sessions
curl http://127.0.0.1:7837/api/v1/sessions | jq

# Quick status
curl http://127.0.0.1:7837/state

# Via unix socket
curl --unix-socket ~/.local/share/irrlicht/irrlichd.sock \
  http://localhost/api/v1/sessions