Agent Skills › sandgardenhq/sgai › session-control

session-control

GitHub

用于在sgai工作区中启动、停止和监控AI代理会话，支持脑暴与自动驾驶模式，并提供编辑器及终端集成接口。

docs/sgai-skills/session-control/SKILL.md sandgardenhq/sgai

触发场景

需要启动或停止AI代理会话检查工作区会话状态在本地或编辑器中打开工作区

安装

npx skills add sandgardenhq/sgai --skill session-control -g -y

更多选项

非标准路径

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

不安装直接使用

npx skills use sandgardenhq/sgai@session-control

指定 Agent (Claude Code)

npx skills add sandgardenhq/sgai --skill session-control -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": "session-control",
    "description": "Start and stop agentic sessions in sgai workspaces. Use when you need to launch AI agent sessions or halt running sessions.",
    "compatibility": "Requires a running sgai server with workspaces that have a GOAL.md configured."
}

Session Control

Sessions are the running instances of AI agents working on a workspace. Each workspace can have at most one running session.

Start a Session

Endpoint: POST /api/v1/workspaces/{name}/start

# Brainstorming mode (interactive, pauses for human input)
curl -X POST $BASE_URL/api/v1/workspaces/my-project/start \
  -H "Content-Type: application/json" \
  -d '{"auto": false}'

# Self-drive mode (fully autonomous, no pausing)
curl -X POST $BASE_URL/api/v1/workspaces/my-project/start \
  -H "Content-Type: application/json" \
  -d '{"auto": true}'

Request:

{"auto": true}

Response:

{
  "name": "my-project",
  "status": "running",
  "running": true,
  "message": "session started"
}

Session Modes

Mode	`auto`	Description
Brainstorming	`false`	Pauses at key decision points to ask for input
Self-drive	`true`	Runs fully autonomously without interruption
Continuous	(auto-detected)	If workspace has a `continuous.md` prompt, uses continuous mode

Notes:

Root workspaces cannot start agentic work (only forks/standalone can)
If already running, returns "message": "session already running"

Stop a Session

Endpoint: POST /api/v1/workspaces/{name}/stop

curl -X POST $BASE_URL/api/v1/workspaces/my-project/stop

Response:

{
  "name": "my-project",
  "status": "stopped",
  "running": false,
  "message": "session stopped"
}

If already stopped: "message": "session already stopped"

Check Running Status

Use the full state endpoint to check session status:

STATE=$(curl -s $BASE_URL/api/v1/state)
RUNNING=$(echo $STATE | jq '.workspaces[] | select(.name=="my-project") | .running')
TASK=$(echo $STATE | jq -r '.workspaces[] | select(.name=="my-project") | .task')

Key workspace state fields for session monitoring:

Field	Type	Description
`running`	bool	Is session active?
`inProgress`	bool	Is work actively happening?
`task`	string	Current task description
`status`	string	Workflow status string
`latestProgress`	string	Most recent progress note

Open in OpenCode (Local Only)

Open the workspace in OpenCode terminal (localhost connections only).

Endpoint: POST /api/v1/workspaces/{name}/open-opencode

curl -X POST http://localhost:PORT/api/v1/workspaces/my-project/open-opencode

Response:

{
  "opened": true,
  "message": "opened in opencode"
}

Errors:

403 — remote connections not allowed (localhost only)
409 — session not running

Open in Editor

Open the workspace directory in the configured editor (VS Code, etc.).

Endpoint: POST /api/v1/workspaces/{name}/open-editor

curl -X POST $BASE_URL/api/v1/workspaces/my-project/open-editor

Response:

{
  "opened": true,
  "editor": "code",
  "message": "opened in editor"
}

Open Specific Files

# Open GOAL.md in editor
curl -X POST $BASE_URL/api/v1/workspaces/my-project/open-editor/goal

# Open PROJECT_MANAGEMENT.md in editor
curl -X POST $BASE_URL/api/v1/workspaces/my-project/open-editor/project-management