gotify

name

gotify

description

This skill should be used when the user asks to "send notification", "notify me when done", "push notification", "alert me", "Gotify notification", "notify on completion", "send push alert", "get messages", "list applications", "gotify health", or mentions push notifications, task alerts, or Gotify. This skill is also automatically invoked without user request for long-running tasks >5 minutes, plan completion, user input required, or task transitions.

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