WebSocket Events

Connect to the daemon WebSocket for real-time updates. The GUI uses this connection to keep the dashboard in sync.

ws://localhost:31415/ws

Connection

const ws = new WebSocket('ws://localhost:31415/ws');

ws.onmessage = (event) => {
  const { event: type, data } = JSON.parse(event.data);
  console.log(type, data);
};

Origin verification

The WebSocket server verifies the Origin header and only accepts connections from localhost. This matches the REST API's CORS policy.

Agent Events

agent:spawned

Fired when a new agent is spawned.

{
  "event": "agent:spawned",
  "data": {
    "id": "backend-1",
    "role": "backend",
    "provider": "claude-code",
    "model": "claude-sonnet-4-6",
    "scope": ["src/api/**"],
    "peers": ["frontend-1"]
  }
}

agent:killed

Fired when an agent is killed.

{
  "event": "agent:killed",
  "data": {
    "id": "backend-1",
    "reason": "manual"
  }
}

agent:status

Fired on agent status changes -- context usage updates, state transitions, model changes.

{
  "event": "agent:status",
  "data": {
    "id": "backend-1",
    "status": "active",
    "contextUsage": 0.45,
    "model": "claude-sonnet-4-6"
  }
}

Rotation Events

rotation:start

Fired when context rotation begins for an agent.

{
  "event": "rotation:start",
  "data": {
    "agentId": "backend-1",
    "reason": "context_threshold",
    "contextUsage": 0.76
  }
}

rotation:complete

Fired when context rotation finishes successfully. The old agent has been killed and the new one is running.

{
  "event": "rotation:complete",
  "data": {
    "old": "backend-1",
    "new": "backend-2",
    "reason": "context_threshold",
    "handoffBrief": true
  }
}

rotation:failed

Fired when context rotation fails -- for example, if the new agent fails to spawn.

{
  "event": "rotation:failed",
  "data": {
    "agentId": "backend-1",
    "error": "Failed to spawn replacement agent",
    "reason": "context_threshold"
  }
}

rotation:triggered

Fired when auto-rotation is triggered by the adaptive threshold engine. This fires before rotation:start and indicates that the system has decided to rotate.

{
  "event": "rotation:triggered",
  "data": {
    "old": "backend-1",
    "new": "backend-2",
    "reason": "context_threshold"
  }
}

Journalist Events

journalist:update

Fired when the Journalist completes a synthesis cycle and updates project documents.

{
  "event": "journalist:update",
  "data": {
    "projectMap": true,
    "decisions": true,
    "timestamp": "2026-04-05T00:30:00Z"
  }
}

journalist:cycle

Fired when a Journalist cycle starts, either on the configured interval or from a manual trigger.

{
  "event": "journalist:cycle",
  "data": {
    "trigger": "interval",
    "activeAgents": 3,
    "timestamp": "2026-04-05T00:30:00Z"
  }
}

Listening for Specific Events

Filter events on the client side by checking the event field:

const ws = new WebSocket('ws://localhost:31415/ws');

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);

  switch (msg.event) {
    case 'agent:spawned':
      console.log(`New agent: ${msg.data.id}`);
      break;
    case 'rotation:complete':
      console.log(`Rotated ${msg.data.old} -> ${msg.data.new}`);
      break;
    case 'journalist:update':
      console.log('Project docs updated');
      break;
  }
};