Agent Skills › sandgardenhq/sgai › monitoring

monitoring

GitHub

监控sgai工作区状态、事件及进度，支持获取完整工厂状态、单工作区详情及通过SSE订阅实时更新，用于观察代理行为与追踪任务进展。

docs/sgai-skills/monitoring/SKILL.md sandgardenhq/sgai

Trigger Scenarios

需要观察agent正在做什么需要追踪任务进度或获取工作区当前状态需要订阅实时状态更新

Install

npx skills add sandgardenhq/sgai --skill monitoring -g -y

More Options

Non-standard path

npx skills add https://github.com/sandgardenhq/sgai/tree/main/docs/sgai-skills/monitoring -g -y

Use without installing

npx skills use sandgardenhq/sgai@monitoring

指定 Agent (Claude Code)

npx skills add sandgardenhq/sgai --skill monitoring -a claude-code -g -y

安装 repo 全部 skill

npx skills add sandgardenhq/sgai --all -g -y

预览 repo 内 skill

npx skills add sandgardenhq/sgai --list

SKILL.md

Frontmatter

{
    "name": "monitoring",
    "description": "Monitor sgai workspace status, events, progress, and workflow diagrams. Use when you need to observe what agents are doing, track progress, get the current state of all workspaces, or subscribe to real-time updates via SSE.",
    "compatibility": "Requires a running sgai server. SSE streaming requires a client that supports Server-Sent Events."
}

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",
      "task": "Writing authentication endpoints",
      "latestProgress": "Created JWT middleware",
      "cost": {
        "inputTokens": 45000,
        "outputTokens": 12000,
        "cacheCreationInputTokens": 8000,
        "cacheReadInputTokens": 32000
      },
      "events": [...],
      "projectTodos": [...],
      "agentTodos": [...],
      "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.
`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

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 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"
  }
]