Appearance

WebSocket Events ​

Connect to the daemon WebSocket for real-time updates. The GUI and chat gateways both use this connection to stay in sync.

ws://localhost:31415

Connection ​

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

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

On connection, the server immediately sends a state message with the full agent registry. Subsequent messages push incremental updates.

Origin verification

The WebSocket server verifies the Origin header and only accepts connections from localhost origins. This matches the REST API's CORS policy. Connections without an origin (CLI/native clients) are always allowed.

State Sync ​

state ​

Fired on any agent registry change — spawn, update, remove, status change. Contains the full agent list.

json
{
  "type": "state",
  "data": [
    {
      "id": "ab12cd34",
      "name": "backend-1",
      "role": "backend",
      "status": "running",
      "provider": "claude-code",
      "model": "claude-sonnet-4-6",
      "scope": ["src/api/**"],
      "tokensUsed": 45000,
      "contextUsage": 0.45,
      "spawnedAt": "2026-04-09T10:00:00Z"
    }
  ]
}

Agent Events ​

agent:output ​

Fired when an agent writes structured output to stdout. High-frequency — used by the GUI for real-time activity feeds.

json
{
  "type": "agent:output",
  "agentId": "ab12cd34",
  "data": {
    "type": "activity",
    "subtype": "assistant",
    "data": "Refactoring the auth middleware..."
  }
}

Output subtypes: assistant (AI text), tool (tool use), result (final output), usage (token counts).

agent:exit ​

Fired when an agent process exits.

json
{
  "type": "agent:exit",
  "agentId": "ab12cd34",
  "code": 0,
  "signal": null,
  "status": "completed"
}

Status values: completed (code 0), crashed (non-zero code), killed (signal termination).

Rotation Events ​

rotation:start ​

Fired when context rotation begins.

json
{
  "type": "rotation:start",
  "agentId": "ab12cd34",
  "agentName": "backend-1"
}

rotation:complete ​

Fired when rotation finishes — old agent killed, new agent spawned with handoff brief.

json
{
  "type": "rotation:complete",
  "agentId": "ef56gh78",
  "agentName": "backend-1",
  "oldAgentId": "ab12cd34",
  "tokensSaved": 45000
}

rotation:failed ​

Fired when rotation fails.

json
{
  "type": "rotation:failed",
  "agentId": "ab12cd34",
  "error": "Failed to spawn replacement agent"
}

Approval Events ​

approval:request ​

Fired when an agent triggers a scope violation that needs human review.

json
{
  "type": "approval:request",
  "data": {
    "id": "approval-1712678400-1",
    "agentId": "ab12cd34",
    "agentName": "backend-1",
    "action": {
      "type": "scope_violation",
      "description": "Agent tried to modify src/auth.js (owned by frontend-1)"
    },
    "status": "pending",
    "requestedAt": "2026-04-09T12:00:00Z"
  }
}

approval:resolved ​

Fired when an approval is approved or rejected.

json
{
  "type": "approval:resolved",
  "data": {
    "id": "approval-1712678400-1",
    "status": "approved",
    "resolvedAt": "2026-04-09T12:01:00Z"
  }
}

Conflict Events ​

conflict:detected ​

Fired when an agent attempts to modify a file owned by another agent.

json
{
  "type": "conflict:detected",
  "data": {
    "agentName": "backend-1",
    "filePath": "src/index.js",
    "ownerName": "frontend-1"
  }
}

Journalist Events ​

journalist:cycle ​

Fired when the Journalist completes a synthesis cycle.

json
{
  "type": "journalist:cycle",
  "data": {
    "cycleCount": 3,
    "lastCycleTime": "2026-04-09T12:02:00Z",
    "lastSynthesis": "Backend API refactored, frontend components updated..."
  }
}

Team Events ​

team:created ​

json
{
  "type": "team:created",
  "team": { "id": "ab12cd34", "name": "Backend Squad" }
}

team:updated ​

json
{
  "type": "team:updated",
  "team": { "id": "ab12cd34", "name": "API Team" }
}

team:deleted ​

json
{
  "type": "team:deleted",
  "teamId": "ab12cd34",
  "movedTo": "default-team-id"
}

Schedule Events ​

schedule:execute ​

Fired when a scheduled agent is spawned by the cron scheduler.

json
{
  "type": "schedule:execute",
  "scheduleId": "ab12cd34",
  "agentId": "ef56gh78"
}

Gateway Events ​

gateway:status ​

Fired when any gateway connects, disconnects, or is updated. Contains the full list of gateways.

json
{
  "type": "gateway:status",
  "data": [
    {
      "id": "telegram-abc123",
      "type": "telegram",
      "connected": true,
      "enabled": true,
      "chatId": "123456789"
    }
  ]
}

Other Events ​

phase2:spawned ​

Fired when a QC agent is auto-spawned after all phase 1 builders complete.

json
{
  "type": "phase2:spawned",
  "agentId": "ab12cd34",
  "name": "qc-senior-dev",
  "role": "fullstack"
}

qc:activated ​

Fired when the QC threshold is reached (4+ agents by default).

json
{
  "type": "qc:activated",
  "agentCount": 4
}

file:changed ​

Fired when a watched file is modified (editor integration, 300ms debounce).

json
{
  "type": "file:changed",
  "path": "src/index.js",
  "timestamp": 1712678400000
}

Classifier Events ​

classifier:update ​

Fired every 20 events once the classifier has 40+ data points for an agent. Powers mid-session downshift suggestions in the GUI.

json
{
  "type": "classifier:update",
  "agentId": "ab12cd34",
  "tier": "light",
  "eventCount": 60
}

Tier values: light, medium, heavy.

Coordination Events ​

coordination:declared ​

Fired when an agent acquires an exclusive lock on shared resources via POST /api/coordination/declare.

json
{
  "type": "coordination:declared",
  "agentId": "ab12cd34",
  "operation": "npm install",
  "resources": ["package.json", "node_modules"]
}

coordination:completed ​

Fired when an agent releases a coordination lock via POST /api/coordination/complete or when the 10-minute TTL expires.

json
{
  "type": "coordination:completed",
  "agentId": "ab12cd34"
}

Memory Events (Layer 7) ​

memory:constraint:added ​

Fired when a new project constraint is added to persistent memory.

json
{
  "type": "memory:constraint:added",
  "hash": "a1b2c3d4e5f6"
}

memory:constraint:removed ​

Fired when a project constraint is removed by its hash.

json
{
  "type": "memory:constraint:removed",
  "hash": "a1b2c3d4e5f6"
}

memory:discovery:added ​

Fired when an agent records a successful error→fix pair to the discovery log.

json
{
  "type": "memory:discovery:added",
  "agentId": "ab12cd34",
  "role": "backend"
}

Rotation Reason Codes ​

The rotation:complete event's reason field can be any of:

ReasonTrigger
context_thresholdAdaptive threshold reached (context fullness)
quality_degradationQuality score dropped below threshold
natural_compactionProvider-managed context reset (no GROOVE action)
token_limit_exceededAgent burned more than safety.tokenCeilingPerAgent since spawn
runaway_velocity(removed in v0.27.2) — legacy rotations may still appear in saved history
manualUser-triggered via GUI or CLI

Listening for Specific Events ​

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

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

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

  switch (msg.type) {
    case 'state':
      console.log(`${msg.data.length} agents`);
      break;
    case 'agent:exit':
      console.log(`Agent ${msg.agentId} ${msg.status}`);
      break;
    case 'approval:request':
      console.log(`Approval needed: ${msg.data.id}`);
      break;
    case 'rotation:complete':
      console.log(`Rotated: ${msg.oldAgentId} -> ${msg.agentId}`);
      break;
    case 'gateway:status':
      console.log(`${msg.data.length} gateways`);
      break;
  }
};

Last updated:

FSL-1.1-Apache-2.0

© 2026 Groove Dev