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:

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.
Plan Completion: After finishing implementation of a plan or major milestone
User Input Required: When blocked and need user decisions/clarifications
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

gotify

Gotify Skill

Tools

gotify — Action Router

gotify_help — Help and Discovery

Action Reference

Messages

Applications

Clients

Server Info

Resources

HTTP Fallback Mode

Send a notification

With markdown

List messages / applications

Health check (no auth)

Management operations (fallback)

Mandatory Automatic Notification Workflows

1. Long Running Task Completes (>5 min)

2. Plan Implementation Finishes

3. Blocked — Need User Input

4. Task Transition — Need Review/Approval

Notification Format Requirements

Priority Reference

Notes

`gotify` — Action Router

`gotify_help` — Help and Discovery