AI Agents & MCP

Set up nudge notifications for Claude Code, Cursor, Windsurf, and MCP servers.

nudge.sh integrates with any AI coding agent that can run shell commands or be configured with hooks. Get a text message the moment your agent finishes a task.

Claude Code

The recommended way to use nudge.sh with Claude Code is to install the nudge skill. This teaches Claude to send you a nudge whenever you ask:

terminal

npx skills add dotsquare-labs/nudge-skill

Then set your token as an environment variable in your shell profile:

bash

export NUDGE_TOKEN="ndg_your_token_here"

Now just tell Claude things like "run the tests and nudge me when done" or "deploy this and ping me when finished". The skill handles token discovery, sending the notification, and error handling automatically.

Automatic hooks alternative

Want a nudge after every task without asking? Add a PostToolUse hook in .claude/settings.json instead:

.claude/settings.json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Stop",
        "hooks": [
          {
            "type": "command",
            "command": "curl -s -X POST https://nudge.sh/nudge -H \"X-Nudge-Token: $NUDGE_TOKEN\" -d message=\"claude-code task done\""
          }
        ]
      }
    ]
  }
}

Cursor

Cursor's AI agent can execute terminal commands. Add a post-task nudge by including a curl call in your Cursor rules or by appending it to your agent's workflow. In your project's .cursor/rules file:

.cursor/rules

# After completing any task, run this command to notify me:
curl -s -X POST https://nudge.sh/nudge \
  -H "X-Nudge-Token: $NUDGE_TOKEN" \
  -d message="cursor task done"

The agent will pick up this instruction and run the curl command in the terminal when it completes a task.

Windsurf

Windsurf's Cascade agent works similarly to Cursor. Add a nudge instruction to your project's .windsurfrules file:

.windsurfrules

# After completing any task, run this command to notify me:
curl -s -X POST https://nudge.sh/nudge \
  -H "X-Nudge-Token: $NUDGE_TOKEN" \
  -d message="windsurf task done"

MCP Server

nudge.sh provides an MCP server that any MCP-compatible client can use. This gives AI agents a native nudge tool instead of relying on shell commands.

Add the nudge MCP server to your project's .mcp.json or your client's MCP configuration:

.mcp.json

{
  "mcpServers": {
    "nudge": {
      "type": "http",
      "url": "https://nudge.sh/mcp",
      "headers": {
        "Authorization": "Bearer ndg_your_token_here"
      }
    }
  }
}

Works everywhere

This configuration works with any MCP-compatible client including Claude Code, Claude Desktop, Cursor, Windsurf, and Gemini CLI. The nudge tool accepts message, output, exit_code, and metadata parameters.

Once configured, the agent will have access to a nudge tool and can notify you directly without needing curl.

Custom Agent Integration

For any AI agent or automation that can run shell commands, append a curl call after your task completes. The pattern is the same regardless of the tool:

bash

# Generic pattern: your-command && nudge
your-agent-command && curl -s -X POST https://nudge.sh/nudge \
  -H "X-Nudge-Token: $NUDGE_TOKEN" \
  -d message="task done"

To capture success or failure and include the exit code:

bash

# Capture exit code for pass/fail reporting
your-agent-command
EXIT_CODE=$?
curl -s -X POST https://nudge.sh/nudge \
  -H "X-Nudge-Token: $NUDGE_TOKEN" \
  -d message="task done" \
  -d exit_code=$EXIT_CODE

Keep your token secure

Never hardcode your API token in files committed to version control. Always use environment variables or a secrets manager. Add .env to your .gitignore.

Next Steps

Previous CI/CD Next Language Examples