setup

Setup ntfy Notifications

Guide the user through setting up ntfy notifications for claude-ntfy. Supports both new server setup and configuration of existing servers.

Reference

• Config diagnostics: scripts/detect-config.sh
• Test notification: scripts/test-ntfy.sh
• Configuration guide: docs/CONFIG.md

Overview

This skill helps with three scenarios:

1. New Server Setup - Start a self-hosted ntfy server using Docker
2. Existing Server - Configure claude-ntfy to use an existing ntfy server
3. Public Service (ntfy.sh) - Use the free public ntfy.sh service

Step 0: Detect Existing Configuration

Before asking anything, run the detect script to see what's already configured:

bash "$CLAUDE_PLUGIN_ROOT/scripts/detect-config.sh"

This shows environment variables, config files, resolved configuration, and server connectivity. Use the output to skip steps that are already done and guide the user to what's missing.

Step 1: Clarify Setup Type

Ask the user which setup applies to them:

Which setup scenario applies to you?

1. New Server Setup
   → Start a self-hosted ntfy server using Docker Compose
   → Good for: Local development, isolated setup, full control

2. Existing Server
   → Configure to use an existing ntfy server
   → Good for: Production setups, shared infrastructure, already running

3. Public Service (ntfy.sh)
   → Use the public ntfy.sh service (no setup needed)
   → Good for: Quick testing, no infrastructure cost

Please choose: 1, 2, or 3

---

Scenario 1: New Server Setup

Step 1.1: Check Docker Availability

Run docker --version and docker compose version to verify Docker is installed.

If Docker is not available, tell the user:

• They need Docker installed to run a self-hosted ntfy server
• Alternatively, they can use the public https://ntfy.sh service

Step 1.2: Start the ntfy Server

The plugin includes a Docker Compose file. Start it:

docker compose -f $CLAUDE_PLUGIN_ROOT/docker/docker-compose.yml up -d

Verify it's running:

curl -s http://localhost:8080/v1/health | head -c 200

Expected: a JSON response indicating the server is healthy. If it fails, check:

• Port 8080 is not in use (lsof -i :8080)
• Docker daemon is running

Step 1.3: Choose Configuration Method

Ask the user how they want to configure claude-ntfy:

How would you like to configure claude-ntfy?

A. Environment Variables (Temporary)
   export NTFY_TOPIC="claude-alerts"
   export NTFY_SERVER_URL="http://localhost:8080"

B. Config File (Persistent)
   Create ~/.config/claude-ntfy/config.json
   Good for: Permanent setup, survives shell restarts

Please choose: A or B

Step 1.4: Set Configuration

If A (Environment Variables):

Ask for the topic name and provide the export commands:

export NTFY_TOPIC="claude-alerts"
export NTFY_SERVER_URL="http://localhost:8080"

If B (Config File):

Ask for the topic name, then create ~/.config/claude-ntfy/config.json:

mkdir -p ~/.config/claude-ntfy

{
  "server_url": "http://localhost:8080",
  "topic": "claude-alerts"
}

Step 1.5: Verify Configuration

Guide through verification:

# Send a test notification
curl -H "Title: Test" \
     -d "Claude-ntfy is working!" \
     http://localhost:8080/claude-alerts

---

Scenario 2: Existing Server Configuration

Step 2.1: Detect Existing Configuration

Run the detect script to check for existing configuration:

bash "$CLAUDE_PLUGIN_ROOT/scripts/detect-config.sh"

If configuration exists, show what was found and ask if user wants to:

• Keep existing configuration
• Update it
• Create a new configuration

Step 2.2: Gather Server Information

If no configuration found, ask the user for:

Please provide the following information:

1. Server URL (e.g., https://ntfy.example.com or http://localhost:8080)
   Server URL: [user input]

2. Topic name (e.g., claude-alerts)
   Topic: [user input]

3. Authentication token (if required, leave blank if not)
   Token (optional): [user input]

Step 2.3: Configuration Options

After gathering information, offer configuration options:

How would you like to store this configuration?

A. Environment Variables (for this shell session)
   export NTFY_SERVER_URL="<url>"
   export NTFY_TOPIC="<topic>"
   [if token] export NTFY_TOKEN="<token>"

B. Config File (~/.config/claude-ntfy/config.json)
   Persistent across sessions
   Follows XDG Base Directory specification

Please choose: A or B

Step 2.4: Create Configuration

If A (Environment Variables):

Provide the export commands with the user's values.

If B (Config File):

Create ~/.config/claude-ntfy/config.json:

mkdir -p ~/.config/claude-ntfy

{
  "server_url": "<user-provided-url>",
  "topic": "<user-provided-topic>"
}

If token is provided, include it:

{
  "server_url": "<user-provided-url>",
  "topic": "<user-provided-topic>",
  "token": "<user-provided-token>"
}

If token is included, set restrictive permissions:

chmod 600 ~/.config/claude-ntfy/config.json

Step 2.5: Verify Connection

Test the configuration:

# Test connectivity
curl -I "<server-url>/v1/health"

Expected: HTTP 200 response

---

Scenario 3: Public Service (ntfy.sh)

Step 3.1: Choose Configuration Method

ntfy.sh is public, so just configure the topic and URL:

Using ntfy.sh (public service)

Server: https://ntfy.sh
Topic: [ask user for topic name]

Step 3.2: Create Configuration

Use the same configuration options as Scenario 2.3:

# Environment variable
export NTFY_SERVER_URL="https://ntfy.sh"
export NTFY_TOPIC="<user-chosen-topic>"

Or in ~/.config/claude-ntfy/config.json:

{
  "server_url": "https://ntfy.sh",
  "topic": "<user-chosen-topic>"
}

---

Configuration File Format Reference

Config File Location

~/.config/claude-ntfy/config.json (XDG Base Directory spec)

{
  "server_url": "http://localhost:8080",
  "topic": "claude-alerts",
  "token": "tk_optional_bearer_token"
}

Field	Required	Default	Description
server_url	No	http://localhost:8080	ntfy server URL
topic	Yes	—	ntfy topic to publish to
token	No	—	Bearer token for authentication

---

Configuration Precedence

When claude-ntfy loads, it uses this precedence (highest to lowest):

1. Environment variables (NTFY_SERVER_URL, NTFY_TOPIC, NTFY_TOKEN)
2. Config file (~/.config/claude-ntfy/config.json)
3. Defaults (server: http://localhost:8080)

---

Verification Checklist

After setup, verify:

• Server is running/reachable
• Configuration loaded correctly
• NTFY_TOPIC is set (required)
• NTFY_SERVER_URL is accessible
• NTFY_TOKEN is correct (if using authentication)
• Plugin is installed: claude plugin list | grep ntfy

---

Next Steps

After setup is complete:

1. Install the plugin (if not already installed):

   claude plugin add /path/to/claude-ntfy
   

2. Test notifications using the test-ntfy skill:

   "Send a test notification to verify setup"
   

3. Start Claude Code - Notifications will now be sent automatically

---

Troubleshooting

Configuration not being recognized

# Run the detect script to see all config sources
bash "$CLAUDE_PLUGIN_ROOT/scripts/detect-config.sh"

Precedence: env vars > config file > defaults

Server connection issues

# Test connectivity to server
curl -I "${NTFY_SERVER_URL:-http://localhost:8080}/v1/health"

# If using Docker locally, check it's running
docker ps | grep ntfy

# Check if port is in use
lsof -i :8080

Authentication failures

• Verify NTFY_TOKEN is set correctly
• Check token format (should be tk_...)
• Verify server requires authentication

Docker issues

• Ensure Docker daemon is running
• Check disk space: docker system df
• Review logs: docker logs ntfy

---

Reference

• ntfy Documentation: https://docs.ntfy.sh/
• Configuration Guide: See docs/CONFIG.md
• Test Notification Skill: Use test-ntfy skill after setup