NockIt Docs — Setup & CLI Reference

Quick start

60 seconds, three commands

1

Run the interactive setup

npx -y nockit-mcp setup

This creates your private notification topic and configures your agent. You can pass --force to reconfigure an existing setup.

2

Subscribe to your topic

In the free ntfy app on your phone, tap "Add subscription" and paste the topic URL shown by setup — for example:

https://ntfy.sh/nockit_a1b2c3d4

3

Restart your agent

Restart OpenCode, Claude Code, Cursor, Zed, or any MCP-compatible client. NockIt now pings your phone when your agent finishes, fails, or needs input.

Configuration

Manual setup

Prefer to configure by hand? Add nockit to your MCP client's config file, pointing it at your topic via the NTFY_TOPIC environment variable.

{
  "mcpServers": {
    "nockit": {
      "command": "npx",
      "args": ["-y", "nockit-mcp"],
      "env": {
        "NTFY_TOPIC": "your_chosen_topic"
      }
    }
  }
}

Works with Claude Desktop, Cursor, Zed, and any client that supports MCP servers.

CLI reference

Command line

npx nockit setup

Interactively configure your topic, rules, and agent settings. Pass --force to reconfigure.

npx nockit status

Show your active topic, ntfy URL, and configuration file paths.

npx nockit send

Push a manual notification from your terminal or shell scripts.

Manual send examples

# Task done
npx nockit send --status completed --summary "Build and tests passed!"

# Need user input
npx nockit send --status needs_input --summary "API key required for Stripe integration."

# Something broke
npx nockit send --status failed --summary "Database migration failed on line 42."

You can also run npx -y nockit-mcp send ... if nockit isn't installed locally.

Delivery channels

Ping your phone — or your whole team

During setup, NockIt asks for optional webhook URLs. Every notification is forwarded to all the channels you configure, alongside your ntfy phone push.

ntfy — phone push

Free push notifications straight to your phone, always on. Subscribe to your private topic in the ntfy app and you're set.

ntfy.sh

Discord

Paste a webhook URL during setup and every agent alert is posted to any Discord channel you choose.

Create a webhook →

Slack

An incoming webhook URL posts alerts straight into your Slack channel — perfect for sharing agent progress with your team.

Slack webhooks →

Telegram

Point your own bot at a chat id and get a direct message every time your agent pings. Great for private, personal alerts.

Create a bot →

Troubleshooting

Common issues

Notifications aren't reaching my phone

Run npx nockit status to confirm your topic, then verify you're subscribed to that exact topic URL in the ntfy app. The topic name is case-sensitive.

I want to change my topic or channels

Re-run npx -y nockit-mcp setup --force to reconfigure your topic, delivery channels, and agent settings.

The command isn't found

Always use npx -y nockit-mcp setup. The -y flag ensures the latest package is installed even when it isn't cached locally.

Does NockIt send data anywhere?

NockIt runs entirely on your machine. Only the notification message leaves your laptop, sent to your private ntfy topic (and any channels you configured).

What statuses does NockIt send?

Three types: completed when a task finishes, needs_input when the agent is blocked and waiting for you, and failed when an unrecoverable error stops the agent.

Which AI coding agents are supported?

NockIt works with any MCP-compatible client, including OpenCode, Claude Code, Cursor, and Zed. See the homepage for more.

Is NockIt free?

Yes. NockIt is MIT-licensed open source and free to use, and push notifications via ntfy.sh are free as well.

NockIt docs & setup guide