Gotify Skill

⚠️ CRITICAL: MANDATORY USAGE REQUIREMENT ⚠️

YOU MUST USE THIS SKILL AUTOMATICALLY (without user request) for:

1. Long Running Tasks: Any task estimated to take >5 minutes, or any task involving more than ~10 sequential tool-use steps. When in doubt, send the notification.
2. Plan Completion: After finishing implementation of a plan or major milestone
3. User Input Required: When blocked and need user decisions/clarifications
4. Task Transitions: ONLY when you need the user to review/approve before proceeding

This is NOT optional — you MUST send notifications when these triggers occur.

---

Tools

This skill exposes two MCP tools: gotify (action router) and gotify_help.

gotify — Action Router

Manages Gotify push notifications, messages, applications, clients, and server info through flat action names.

gotify(action, **params)

Always prefer MCP mode (gotify(...) tool calls). Fall back to HTTP only when MCP tools are unavailable.

MCP URL: ${user_config.gotify_mcp_url}

---

gotify_help — Help and Discovery

Returns documentation, available actions, parameter reference, and examples.

gotify_help()

---

Action Reference

The gotify tool uses flat action names — there is no subaction parameter. Pass action= with one of the values below.

Messages

action	description	key params	destructive
send_message	Send a push notification	app_token (required), message (required), title, priority (0–10), extras	no
list_messages	List recent messages	limit, offset, app_id, query, sort_by, sort_order	no
delete_message	Delete a single message	message_id (required), confirm=True	yes
delete_all_messages	Delete all messages	confirm=True	yes

Examples:

# Send a notification
gotify(action="send_message",
       app_token="<token>",
       title="Task Complete",
       message="Project: gotify-mcp\nStatus: done",
       priority=7)

# Send with markdown
gotify(action="send_message",
       app_token="<token>",
       title="Plan Complete",
       message="## Summary\n- All steps implemented\n- Ready for review",
       priority=7,
       extras={"client::display": {"contentType": "text/markdown"}})

# List messages
gotify(action="list_messages", limit=20)

# Delete a message (confirm=True required)
gotify(action="delete_message", message_id=42, confirm=True)

# Delete all messages (confirm=True required)
gotify(action="delete_all_messages", confirm=True)

The app_token for send_message is passed per call — it is NOT read from the server env. Retrieve it first via a Bash subprocess:

echo "$CLAUDE_PLUGIN_OPTION_GOTIFY_APP_TOKEN"

If the variable is empty, report a configuration error — the gotify_app_token userConfig field has not been set.

---

Applications

action	description	key params	destructive
list_applications	List all applications	offset, limit, query	no
create_application	Create a new application	name (required), description, default_priority	no
update_application	Update an existing application	app_id (required), name, description, default_priority	no
delete_application	Delete an application	app_id (required), confirm=True	yes

Examples:

# List applications
gotify(action="list_applications")

# Create an application
gotify(action="create_application",
       name="homelab-alerts",
       description="Claude Code homelab notifications",
       default_priority=5)

# Update an application
gotify(action="update_application",
       app_id=3, name="homelab-alerts-v2", default_priority=7)

# Delete an application (confirm=True required)
gotify(action="delete_application", app_id=3, confirm=True)

---

Clients

Manages Gotify clients (subscribers that receive notifications).

action	description	key params	destructive
list_clients	List all clients	—	no
create_client	Create a new client	name (required)	no
delete_client	Delete a client	client_id (required), confirm=True	yes

Examples:

# List clients
gotify(action="list_clients")

# Create a client
gotify(action="create_client", name="my-phone")

# Delete a client (confirm=True required)
gotify(action="delete_client", client_id=5, confirm=True)

---

Server Info

Retrieves server health and version information. Note: MCP tool calls still require bearer authentication. Only the raw /health HTTP endpoint is unauthenticated.

action	description	key params
health	Check server health	—
version	Get server version	—

Examples:

# Health check
gotify(action="health")

# Version info
gotify(action="version")

---

Resources

gotify://application/{app_id}/messages   — messages for a specific app
gotify://currentuser                     — current authenticated user info

---

HTTP Fallback Mode

Use when MCP tools are unavailable. Credentials are in the subprocess environment as CLAUDE_PLUGIN_OPTION_* vars — use these directly in Bash subprocesses.

Send a notification

curl -s -X POST "$CLAUDE_PLUGIN_OPTION_GOTIFY_URL/message" \
  -H "X-Gotify-Key: $CLAUDE_PLUGIN_OPTION_GOTIFY_APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"title\":\"$TITLE\",\"message\":\"$MESSAGE\",\"priority\":$PRIORITY}"

With markdown

curl -s -X POST "$CLAUDE_PLUGIN_OPTION_GOTIFY_URL/message" \
  -H "X-Gotify-Key: $CLAUDE_PLUGIN_OPTION_GOTIFY_APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"title\":\"$TITLE\",\"message\":\"$MESSAGE\",\"priority\":5,\"extras\":{\"client::display\":{\"contentType\":\"text/markdown\"}}}"

List messages / applications

# Messages
curl -s "$CLAUDE_PLUGIN_OPTION_GOTIFY_URL/message" \
  -H "X-Gotify-Key: $CLAUDE_PLUGIN_OPTION_GOTIFY_CLIENT_TOKEN"

# Applications
curl -s "$CLAUDE_PLUGIN_OPTION_GOTIFY_URL/application" \
  -H "X-Gotify-Key: $CLAUDE_PLUGIN_OPTION_GOTIFY_CLIENT_TOKEN"

Health check (no auth)

curl -s "$CLAUDE_PLUGIN_OPTION_GOTIFY_URL/health"

Management operations (fallback)

# Delete a message
curl -s -X DELETE "$CLAUDE_PLUGIN_OPTION_GOTIFY_URL/message/$MESSAGE_ID" \
  -H "X-Gotify-Key: $CLAUDE_PLUGIN_OPTION_GOTIFY_CLIENT_TOKEN"

# Create application
curl -s -X POST "$CLAUDE_PLUGIN_OPTION_GOTIFY_URL/application" \
  -H "X-Gotify-Key: $CLAUDE_PLUGIN_OPTION_GOTIFY_CLIENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"name\":\"$APP_NAME\"}"

---

Mandatory Automatic Notification Workflows

1. Long Running Task Completes (>5 min)

gotify(action="send_message",
       app_token="<retrieve via: bash -c 'echo $CLAUDE_PLUGIN_OPTION_GOTIFY_APP_TOKEN'>",
       title="Task Complete",
       message="Project: <basename of cwd>\nTask: <description>\nSession: <session-YYYY-MM-DD-HH-MM>\nStatus: Completed successfully",
       priority=7)

2. Plan Implementation Finishes

gotify(action="send_message",
       app_token="<retrieve via: bash -c 'echo $CLAUDE_PLUGIN_OPTION_GOTIFY_APP_TOKEN'>",
       title="Plan Complete",
       message="Project: <basename of cwd>\nTask: <plan description>\nStatus: All steps implemented\nNext: Ready for review",
       priority=7)

3. Blocked — Need User Input

gotify(action="send_message",
       app_token="<retrieve via: bash -c 'echo $CLAUDE_PLUGIN_OPTION_GOTIFY_APP_TOKEN'>",
       title="Input Required",
       message="Project: <basename of cwd>\nTask: <current task>\nBlocked: <reason>\nNeed: <what you need from user>",
       priority=8)

4. Task Transition — Need Review/Approval

gotify(action="send_message",
       app_token="<retrieve via: bash -c 'echo $CLAUDE_PLUGIN_OPTION_GOTIFY_APP_TOKEN'>",
       title="Ready to Proceed",
       message="Project: <basename of cwd>\nCompleted: <current phase>\nNext: <next phase>\nAction: Review required before proceeding",
       priority=7)

---

Notification Format Requirements

All notifications MUST include:

• Project/Working Directory: basename of current working directory
• Task Description: Specific task completed or blocked on
• Session ID: Construct as session-YYYY-MM-DD-HH-MM using current UTC timestamp (date -u +session-%Y-%m-%d-%H-%M)
• Status/Next Action: What's done and what needs user attention

---

Priority Reference

Range	Level	Use For
0–3	Low	Info, FYI
4–7	Normal	Task updates, completions
8–10	High	Blocked, errors, urgent

---

Notes

• gotify(action="send_message") always requires an explicit app_token — it is not read from server environment automatically
• Management operations (list, delete, application/client CRUD) use GOTIFY_CLIENT_TOKEN configured in the server env — no token parameter needed
• gotify(action="health") and gotify(action="version") require bearer authentication (like all MCP tool calls). The raw HTTP /health endpoint is unauthenticated.
• Markdown is supported in the message field for both MCP and HTTP modes
• Confirm notification sent: gotify(...) returns JSON with message ID on success