sandgardenhq/monitoring

Monitoring

Monitor the sgai factory to understand what agents are doing and track their progress.

Get Full Factory State

Returns all workspaces and their complete state.

Endpoint: GET /api/v1/state

curl -s $BASE_URL/api/v1/state | jq .

Response:

{
  "workspaces": [
    {
      "name": "my-project",
      "dir": "/path/to/workspaces/my-project",
      "running": true,
      "needsInput": false,
      "inProgress": true,
      "pinned": false,
      "isRoot": false,
      "isFork": false,
      "hasSgai": true,
      "status": "working",
      "badgeClass": "badge-running",
      "badgeText": "Running",
      "currentAgent": "go",
      "task": "Writing authentication endpoints",
      "latestProgress": "Created JWT middleware",
      "cost": {
        "inputTokens": 45000,
        "outputTokens": 12000,
        "cacheCreationInputTokens": 8000,
        "cacheReadInputTokens": 32000
      },
      "events": [...],
      "projectTodos": [...],
      "agentTodos": [...],
      "commits": [...],
      "log": [...],
      "pendingQuestion": null,
      "forks": []
    }
  ]
}

Key State Fields

| Field | Description | |-------|-------------| | running | Session is active | | needsInput | Blocked waiting for human response | | inProgress | Work is actively happening | | status | Workflow status: "working", "agent-done", "complete", etc. | | currentAgent | Currently executing agent | | task | Current task being worked on | | latestProgress | Most recent progress note | | pendingQuestion | Non-null when human input needed | | badgeText | Human-readable status badge |

Cost Tracking

"cost": {
  "inputTokens": 45000,
  "outputTokens": 12000,
  "cacheCreationInputTokens": 8000,
  "cacheReadInputTokens": 32000
}

Event Timeline

"events": [
  {
    "timestamp": "2026-02-27T17:00:00Z",
    "formattedTime": "5:00 PM",
    "agent": "coordinator",
    "description": "Planning implementation",
    "showDateDivider": false,
    "dateDivider": ""
  }
]

Get Single Workspace State

Equivalent to filtering state by workspace name:

curl -s $BASE_URL/api/v1/state | jq '.workspaces[] | select(.name == "my-project")'

Or use the MCP tool get_workspace_state:

get_workspace_state(workspace: "my-project")

Real-Time Updates via SSE

Subscribe to state change notifications.

Endpoint: GET /api/v1/signal

curl -s -N $BASE_URL/api/v1/signal

Events emitted:

event: reload
data: {}

event: reload
data: {}

Each reload event means state has changed. Fetch /api/v1/state after receiving one.

SSE with Reconnection

#!/bin/bash
while true; do
  curl -s -N "$BASE_URL/api/v1/signal" | while IFS= read -r line; do
    if [[ "$line" == "event: reload" ]]; then
      echo "State changed, fetching..."
      curl -s $BASE_URL/api/v1/state > /tmp/latest-state.json
    fi
  done
  echo "SSE disconnected, reconnecting..."
  sleep 2
done

Get Workspace Diff

Get the current code changes (jj diff) for a workspace.

Endpoint: GET /api/v1/workspaces/{name}/diff

curl -s $BASE_URL/api/v1/workspaces/my-project/diff

Response:

{
  "diff": "diff --git a/cmd/api/auth.go b/cmd/api/auth.go\nnew file mode 100644\n..."
}

Get Workflow SVG Diagram

Get a visual diagram of the agent workflow.

Endpoint: GET /api/v1/workspaces/{name}/workflow.svg

# Save to file
curl -s $BASE_URL/api/v1/workspaces/my-project/workflow.svg > workflow.svg

# Or open directly in browser
open $BASE_URL/api/v1/workspaces/my-project/workflow.svg

Returns SVG with the agent flow graph. The current agent is highlighted.

Monitor Agent Sequence

The agentSequence field shows the execution history:

curl -s $BASE_URL/api/v1/state | jq '.workspaces[0].agentSequence'

Response:

[
  {
    "agent": "coordinator",
    "model": "openai/gpt-5.5 (xhigh)",
    "elapsedTime": "2m 15s",
    "isCurrent": false
  },
  {
    "agent": "go",
    "model": "openai/gpt-5.5 (low)",
    "elapsedTime": "8m 42s",
    "isCurrent": true
  }
]

Monitor Todos

Check what the agent has planned:

# Project-level todos (from TodoWrite)
curl -s $BASE_URL/api/v1/state | jq '.workspaces[0].projectTodos'

# Agent-level todos (current agent's todo list)
curl -s $BASE_URL/api/v1/state | jq '.workspaces[0].agentTodos'

Todo format:

[
  {
    "id": "todo-1",
    "content": "Implement JWT authentication",
    "status": "in_progress",
    "priority": "high"
  }
]

Monitor Commit History

curl -s $BASE_URL/api/v1/state | jq '.workspaces[0].commits'

Response:

[
  {
    "changeId": "abc123",
    "commitId": "def456",
    "timestamp": "2026-02-27T17:00:00Z",
    "bookmarks": ["main"],
    "description": "cmd/api: add authentication endpoints",
    "graphChar": "◆"
  }
]

Monitor Fork Status

For root workspaces, check their forks:

curl -s $BASE_URL/api/v1/state | jq '.workspaces[] | select(.isRoot) | .forks'

Fork entry:

[
  {
    "name": "feature-auth",
    "dir": "/path/to/workspaces/feature-auth",
    "running": true,
    "needsInput": false,
    "inProgress": true,
    "pinned": false,
    "commitAhead": 3,
    "commits": [...],
    "summary": "Implementing auth"
  }
]