observe - SKILL.md Agent Skill

name: observe description: Agents Observe dashboard and server management argument-hint: [view|stats|status|start|stop|restart|logs-server|logs-cli|logs-mcp|debug] user_invocable: true

/observe

Agents Observe dashboard and server management.

Usage

/observe view — Open the current session in the dashboard
/observe stats — Open the current session's stats modal in the dashboard
/observe — Open the dashboard URL
/observe status — Show server health and config details
/observe start — Start the server
/observe stop — Stop the server
/observe restart — Restart the server
/observe logs-server — Show recent Docker container logs
/observe logs-cli — Tail the local cli.log file
/observe logs-mcp — Tail the local mcp.log file
/observe debug — Diagnose server issues (health, docker logs, mcp.log, cli.log)

Instructions

All commands are invoked via the wrapper at scripts/cli.sh, which resolves the path to observe_cli.mjs relative to this skill's install location. Do not reach outside the skill dir with ../ paths — the agentskills spec disallows it and it breaks portability across agents.

The subcommand is in $ARGUMENTS. If empty, default to showing the dashboard URL.

/observe view

Opens the current session in the dashboard.

Run health to get the dashboard origin:
```
scripts/cli.sh health
```
From the output, take the Dashboard: URL (e.g. http://localhost:4981). If exit code 1, the server isn't running — tell the user to run /observe start and stop here.
Construct the session URL: <dashboard>/#/_/${CLAUDE_SESSION_ID} (the _ is the project placeholder; the dashboard resolves the real project from the session id).
Open it in the user's default browser using the platform-appropriate command — open <url> on macOS, xdg-open <url> on Linux, start <url> on Windows. Pick based on the Platform: line in your environment context.
Also print the URL in your response so the user can re-open it if needed.

/observe stats

Opens the current session's stats modal in the dashboard, using a deep-link URL.

Run health to get the dashboard origin:
```
scripts/cli.sh health
```
From the output, take the Dashboard: URL (e.g. http://localhost:4981). If exit code 1, the server isn't running — tell the user to run /observe start and stop here.
Construct the deep link: <dashboard>/#/_/${CLAUDE_SESSION_ID}:session.stats
Open it in the user's default browser using the platform-appropriate command — open <url> on macOS, xdg-open <url> on Linux, start <url> on Windows. Pick based on the Platform: line in your environment context.
Also print the URL in your response so the user can re-open it if needed.

/observe (no args)

Run:
```
scripts/cli.sh health
```
If exit code 0: show the dashboard URL from the output.
If exit code 1: tell the user the server is not running and suggest /observe start or /observe status.

/observe status

Run:
```
scripts/cli.sh health
```
Show the full output to the user (includes version, runtime, ports, log paths).
If the output contains "Version mismatch", tell the user and offer /observe restart.
If exit code 1, show the output and suggest /observe start.

/observe start

Run:
```
scripts/cli.sh start
```
Show the output to the user. If successful, include the dashboard URL.

/observe stop

Run:
```
scripts/cli.sh stop
```
Confirm to the user that the server has been stopped.

/observe restart

Run:
```
scripts/cli.sh restart
```
Show the output to the user. If successful, include the dashboard URL.

/observe logs-server

Run:
```
scripts/cli.sh logs-server -n 50
```
Show the output to the user. Do NOT use -f (follow) — it would hang.

/observe logs-cli

Run:
```
scripts/cli.sh logs-cli -n 50
```
Show the output to the user.

/observe logs-mcp

Run:
```
scripts/cli.sh logs-mcp -n 50
```
Show the output to the user.

/observe debug

Run these checks in sequence. Read each output before running the next — use what you learn to diagnose the issue.

Server health:
```
scripts/cli.sh health
```
Docker container logs (last 20 lines):
```
scripts/cli.sh logs-server -n 20
```
MCP log (last 20 lines):
```
scripts/cli.sh logs-mcp -n 20
```
CLI log (last 20 lines):
```
scripts/cli.sh logs-cli -n 20
```
Analyze the results and tell the user:
- Is the server running? What version?
- Are there errors in the docker logs? (look for crash loops, port conflicts, DB errors)
- Are there errors in mcp.log? (look for startServer failures, image pull errors)
- Are there errors in cli.log? (look for ECONNREFUSED, hook delivery failures)
- Suggest specific fixes based on what you find.