ntfy CLI for coding agents

When a coding agent runs in a terminal, ntfy lets it send short status messages that you can read on a phone, desktop, or another shell. ntfy organizes messages by topic, a named channel that publishers send to and subscribers listen on. Topics don’t need to be created first. The ntfy CLI has ntfy publish for sending and ntfy subscribe for listening. An agent can also send a message through ntfy’s HTTP interface, using a web request.

For example, an agent can send a brief “checks finished” notification when a long task ends. You can run the CLI to listen for messages on that task’s topic. The commands below connect to the hosted ntfy.sh service, so they require network access. They do not run tests or change your local project files.

Install the CLI

Choose the installation method for your operating system from the official ntfy installation instructions. The CLI and the self-hosted ntfy server are the same ntfy program. On macOS, the docs mention a community-maintained Homebrew formula (brew install ntfy). After installing, check the available commands and options:

ntfy --help
ntfy subscribe --help

The CLI is useful when a shell script or agent needs to receive messages from a topic. If your agent only needs to send a notification, it can use the HTTP API without installing the CLI. ntfy documents that publishing request in its message publishing instructions.

Subscribe to a task topic

The following command listens for new messages on a topic at ntfy’s default host:

ntfy subscribe agent-build-status-example

Replace agent-build-status-example with a topic name you choose. According to the CLI subscription documentation, this form prints each incoming message as one line of JSON, which is easier for a script to parse than display-oriented text. It stays open until you stop it. With --poll, it queries the latest messages and exits instead of waiting for new ones.

You can reach a topic on the public ntfy.sh service over the network. ntfy.sh has no sign-up, so its docs treat the topic name like a password. Anyone who knows the name can read the messages. Keep messages short and avoid sending source code or credentials. Avoid sharing private logs or other sensitive details. For work that needs access controls or private infrastructure, use a self-hosted ntfy server configured for that purpose. The server’s configuration documentation covers its settings. Store any credentials outside the agent’s prompt. The CLI can read a username and password, or an access token, from its client.yml config file.

Send a sample notification

To see the subscription work, keep the ntfy subscribe command running in one terminal. In another, publish a harmless sample message with curl or with the CLI:

curl -d "Agent finished; review the run logs" \
  https://ntfy.sh/agent-build-status-example

ntfy publish agent-build-status-example "Agent finished; review the run logs"

Each command sends a message to the hosted service over the network. Neither one prints a preview first. The CLI receives the notification while the subscription remains open. The sample topic is a placeholder, not a private channel, so use a different name for your own test. Do not treat silence as proof that a task succeeded: the subscriber only reports messages it receives, and the agent must publish an update for a relevant event.

Add a notification to an agent task

An agent can run the same kind of HTTP request after a clearly defined event, such as completing its checks. A prompt might say:

After the requested code changes are complete and the tests have finished, send a short status message to the ntfy topic agent-build-status-example. Include whether the checks passed or failed, but do not include source code, secrets, or logs. Do not claim completion if the tests did not run.

The shell needs network access, and the agent needs to be able to send the message for that instruction to work. To send updates automatically, put the request in a script or agent hook, a command that runs when a chosen event occurs. The CLI also has ntfy publish --wait-cmd, which runs a command and sends a message when it ends. ntfy provides message delivery; it does not decide whether the agent’s work is complete or verify the test result.