Let your agent reach your phone

Set up notifications, answer a question with buttons, and send a written reply from the app.

NTF-AI (short name ntf) gives AI agents phone notifications and replies. It speaks the ntfy protocol, so this guide applies when someone asks for ntf, NTF-AI or ntfy notifications. NTF-AI is an independent app, not affiliated with the ntfy project.

Use NTF-AI on iPhone or iPad with ntf-ai.app. The agent needs a terminal with curl and Python 3; no SDK, account or API key is needed on this public server. The human installs the app, allows notifications, opens a topic link and confirms Subscribe. Delivery still depends on network access and iOS notification settings.

Run these commands in one bash or zsh session. Keep this terminal open for the later steps.

export NTF_AI_TOPIC="agent-$(python3 -c 'import secrets; print(secrets.token_hex(16))')"
export NTF_AI_URL="https://ntf-ai.app/$NTF_AI_TOPIC"
export NTF_AI_ANSWERS_URL="https://ntf-ai.app/$NTF_AI_TOPIC-answers"
printf 'Open on your iPhone or iPad, then confirm Subscribe: %s\n' "$NTF_AI_URL"

Send that link to the human. With the app installed, opening it offers the subscription; confirm Subscribe. If the browser opens instead, use + → Scan QR code in the app to scan a QR containing that exact URL, or paste the topic name into + with ntf-ai.app as the server. Generate a QR locally if needed: do not send a secret topic to a public QR service. There is no automatic subscription without the human's confirmation. Subscribe only to the main topic, never to the -answers topic. Button answers go there so a tap does not send another push to your subscribed topic.

The topic name is the password. Anyone who knows it can read and send messages, including forged answers. Keep topic URLs out of public repos, screenshots, logs and shared agent transcripts. This plain HTTP API recipe is not end-to-end encrypted. HTTPS protects the connection; the server can read the messages. On ntf-ai.app ordinary messages and question bodies are cached for 12 hours; protocol answer text and receipts (acks, clear/delete events) are kept 8 days. This is not a durable queue. Do not treat a topic reply as proof of identity or as permission for unrelated actions. Servers you host may require authentication and have different retention.

2. Send a notification

After the human confirms the subscription:

curl --fail-with-body --max-time 20 -H 'Tags: agent' --data-binary 'Your agent is connected.' "$NTF_AI_URL"

A successful response includes a message id. Ask the human to confirm the phone received it before relying on the channel. An HTTP 200 alone proves server acceptance, not phone delivery.

To send a screenshot or any file, upload it as the message body with PUT. The phone shows images in the notification and in the topic's message list:

curl -sS --fail-with-body --max-time 120 -H 'Tags: agent' -H 'Filename: screenshot.png' \
  -H 'Message: Here is the page after the fix' -T screenshot.png "$NTF_AI_URL"

ntf-ai.app accepts files up to 15 MB and keeps them for 3 hours. To attach a file that is already online, send -H 'Attach: https://example.com/report.pdf' with an ordinary message instead.

3. Ask a question with buttons

This example sends button answers to a second topic, $NTF_AI_TOPIC-answers, which the phone never subscribes to. A fresh request ID distinguishes the answer from other messages and doubles as the question's ntfy sequence_id, so you can settle the question later (section 5). The agent must accept only the expected answers for that ID and stop waiting after a deadline. Save its Unix publish time as the cursor for written replies on the main topic, plus its id for deduplication. Tag every agent message to the main topic agent, including follow-ups and status hooks.

export NTF_AI_REQUEST="$(python3 -c 'import secrets; print(secrets.token_hex(8))')"
python3 - <<'PYCODE' > ntf-ai-question.json
import json, os
url, request = os.environ['NTF_AI_ANSWERS_URL'], os.environ['NTF_AI_REQUEST']
print(json.dumps({
    'topic': os.environ['NTF_AI_TOPIC'],
    'sequence_id': request,
    'title': 'Your agent needs an answer',
    'tags': ['agent'],
    'message': 'Continue the example job? Choose Approve or Reject.',
    'actions': [dict(action='http', label=label, url=url, method='POST',
                     headers={'Content-Type': 'text/plain'},
                     body=f'reply:{request}:{answer}')
                for label, answer in [('Approve', 'approve'), ('Reject', 'reject')]]
}))
PYCODE
curl --fail-with-body --max-time 20 -H 'Content-Type: application/json' \
  --data-binary @ntf-ai-question.json --output ntf-ai-question-response.json https://ntf-ai.app
export NTF_AI_ASKED_AT="$(python3 -c 'import json; print(json.load(open("ntf-ai-question-response.json"))["time"])')"
export NTF_AI_QUESTION_ID="$(python3 -c 'import json; print(json.load(open("ntf-ai-question-response.json"))["id"])')"
printf 'Question message ID: %s\n' "$NTF_AI_QUESTION_ID"

Expand the notification to see Approve and Reject; depending on the device, iOS may ask you to unlock it. You can also tap these buttons in the topic's message list. These are ordinary ntfy http actions. They send the specified request from the phone; they do not grant a coding tool's own permissions automatically.

From NTF-AI 1.26, the app opens on an Inbox, and a question like this one sits at the top under Waiting on you until it is answered or settled (section 5). Tapping it opens the question's page, with the buttons pinned at the bottom and, because it is tagged agent, a reply box (section 4). If only a button answer counts, add the tag no-reply to the question's tags; from NTF-AI 1.26 the app then shows no reply box (the app hides that tag, and ntf ask --no-reply adds it).

To test without a phone tap, the next command makes exactly the POST that Approve would make. Skip it when a human is answering. This is a simulated tap, not evidence of notification delivery or a real person's approval.

curl --fail-with-body --max-time 20 -H 'Content-Type: text/plain' \
  --data-binary "reply:$NTF_AI_REQUEST:approve" "$NTF_AI_ANSWERS_URL"

Read and wait for the matching button response, for at most two minutes:

python3 - <<'PYCODE'
import json, os, time, urllib.request
prefix = 'reply:' + os.environ['NTF_AI_REQUEST'] + ':'
deadline = time.monotonic() + 120
while time.monotonic() < deadline:
    with urllib.request.urlopen(os.environ['NTF_AI_ANSWERS_URL'] + '/json?poll=1&since=all', timeout=10) as r:
        messages = [json.loads(line) for line in r if line.strip()]
    answers = [m['message'][len(prefix):] for m in messages
               if m.get('event') == 'message' and m.get('message') in (prefix+'approve', prefix+'reject')]
    if answers:
        print('Button answer:', answers[0])
        break
    time.sleep(3)
else:
    raise SystemExit('No answer within two minutes; leave the job waiting or ask again.')
PYCODE

Connection errors and rate limits end this small example with an error; handle them before continuing work. For longer sessions use ntfy's streaming API or keep a cursor of processed IDs. Do not reuse a request ID, act on an answer twice, or infer an approval from a timeout.

4. Read a written reply

The human can write back in two places:

Both send an ordinary message on the main topic without the agent tag and with no title. The difference is the tag: from NTF-AI 1.26, a reply sent from the question's page carries exactly one tag, re-<sequence_id>, the question's sequence_id (your $NTF_AI_REQUEST), so it says which question it answers; the app hides that tag. A compose-sheet reply has no tag and says nothing about which question it answers. So take a reply tagged re-$NTF_AI_REQUEST, skip one tagged re- with another ID (it answers another question), and treat an untagged one as the answer to your open question. The phone and agent see the same messages. There is no separate private chat or sender identity, so keep one question open per topic (below). Leave the topic's end-to-end encryption password unset in the app for an agent topic: with one set, the app encrypts what the human writes, and these recipes read plain text.

Your phone can notify you about your own written reply: the app does not suppress messages it sends to a subscribed topic.

For an API-only test, this makes the same POST as a reply typed on the question's page (from NTF-AI 1.26; drop the Tags header for a compose-sheet reply). Skip it if the human is writing in the app.

curl --fail-with-body --max-time 20 -H "Tags: re-$NTF_AI_REQUEST" \
  --data-binary 'Please wait for my review' "$NTF_AI_URL"

Read messages from the question's Unix publish time minus one second, deduplicating ids. Treat those without the agent tag as written replies, but skip one tagged re- with another question's ID (run again after the human sends one):

python3 - <<'PYCODE'
import json, os, urllib.parse, urllib.request
request = os.environ['NTF_AI_REQUEST']
query = urllib.parse.urlencode({'poll': '1', 'since': str(int(os.environ['NTF_AI_ASKED_AT']) - 1)})
with urllib.request.urlopen(os.environ['NTF_AI_URL'] + '/json?' + query, timeout=10) as r:
    for line in r:
        m = json.loads(line)
        tags = m.get('tags') or []
        if m.get('event') != 'message' or 'agent' in tags:
            continue
        names = [t[3:] for t in tags if t.startswith('re-') and len(t) > 3]
        if names and names[0] != request:
            continue  # a reply to another question
        print('Written reply:', m['message'], '(names this question)' if names else '(untagged)')
PYCODE

The human can also attach a photo from the compose sheet. Its download link is in the message's attachment.url; for example, add if m.get('attachment'): print('Attachment:', m['attachment']['url']) inside the loop above and fetch it with curl -fsS -o reply.jpg "<that URL>".

Keep one question outstanding on this topic at a time so later replies have a clear context. Keep a cursor of processed message IDs before acting on a reply; repeated polling above prints the cached replies again. Use a timestamp cursor even after the original question has expired from the server cache. The agent and re- tags are only labels: anyone with the topic name can add or omit them, and an unrelated untagged message can look like a reply. Replies remain unverified; do not treat them as proof of identity or permission for unrelated actions.

The 1.26 reply box is on the question's page in the app, not on the notification banner. Typing on the banner itself works only for a notification that carries a reply link (see Reply link help below).

5. Confirm the answer when you stop waiting

The person's tap only tells them the server took it. Once you have the answer, ack it: one message on the question's sequence, tagged agent,ack, at priority 1, whose body is a short note.

curl --fail-with-body --max-time 20 -H "X-Sequence-ID: $NTF_AI_REQUEST" -H 'Tags: agent,ack' -H 'Priority: 1' \
  --data-binary '✓ Got: Approve' "$NTF_AI_URL"

From NTF-AI 1.26 the app shows an ack as a silent receipt on the question, with your note under it, and hides the ack tag; on every version the question stops looking open on the person's devices. Use ✓ Got: <button label> for a button, ✓ Got your reply for a written reply (don't echo the reply back), or your own short note such as Restarting now. Send another ack on the same sequence to update the note (Restarted, all good); the newest one wins. ntf ack <request id> [note] does this, and sends ✓ Got it when you give no note.

Clients that don't know the ack tag (the app before 1.26, other ntfy apps) show the ack's note in place of the question. To keep the question's text there, or when you stop waiting without an answer, publish the full settle instead: the same sequence_id, title and agent tag, no actions, priority 1, and the question with one outcome line appended. Every client replaces the question with this copy without alerting again.

NTF_AI_OUTCOME='✓ Got: Approve' python3 - <<'PYCODE' > ntf-ai-settled.json
import json, os
print(json.dumps({
    'topic': os.environ['NTF_AI_TOPIC'],
    'sequence_id': os.environ['NTF_AI_REQUEST'],
    'title': 'Your agent needs an answer',
    'tags': ['agent'],
    'priority': 1,
    'message': 'Continue the example job? Choose Approve or Reject.\n\n' + os.environ['NTF_AI_OUTCOME'],
}))
PYCODE
curl --fail-with-body --max-time 20 -H 'Content-Type: application/json' \
  --data-binary @ntf-ai-settled.json https://ntf-ai.app

Its outcome line is the ack's note for an answer, or No answer in 2 min; the agent moved on after a timeout. To drop the question instead, curl -X DELETE "$NTF_AI_URL/$NTF_AI_REQUEST" deletes the whole sequence from the app (a message_delete). The ntf ask command acks an answer and settles a timeout for you; --no-ack skips the ack.

Never withdraw a question with a clear (PUT $NTF_AI_URL/$NTF_AI_REQUEST/clear, a message_clear). In ntfy a clear means "read and dismissed", and the app sends one itself whenever the human reads a message, so the question stays open.

What keeps a question under Waiting on you

From NTF-AI 1.26, a message is under Waiting on you when all of these hold: it has at least one http button (or a reply link), it is less than 7 days old, and the human has not answered it on that device. It leaves the list:

Reading it does not take it out, and neither does a clear. An answer counts for the version it was given on: if you publish a new question with buttons on the same sequence_id, it waits again. The list is only as honest as your settling, so settle or delete every question when you stop waiting, including on a timeout.

Buttons tell the person what kind of message it is. http buttons mean "this needs you": put them only on a question you are waiting on, and settle it when you stop. A view button is just a link to open; use it on notifications that need nothing back.

The ntf command (optional)

Everything above works with curl and Python alone. The ntf command does the same steps in one line each, including the request ID, the reply matching and the timeout. It is one Python 3 file with no dependencies, also installed as ntf-ai. It is not the ntfy command, which is the ntfy project's own tool.

pipx install ntf-ai                         # or: pip install ntf-ai
brew install legitimate-apps/tap/ntf-ai     # or with Homebrew

Or take the single file, with nothing to install:

mkdir -p ~/.local/bin
curl -fsSL -o ~/.local/bin/ntf-ai https://ntf-ai.app/ntf
chmod +x ~/.local/bin/ntf-ai && ln -sf ntf-ai ~/.local/bin/ntf

Then:

ntf topic new --save                          # long random topic, saved to ~/.config/ntf-ai/config.json
ntf link                                      # the subscribe link; draws a QR code on a terminal
ntf send "Build finished"
ntf send --attach screenshot.png "Here is the page after the fix"
ntf ask "Merge PR 42 into main?"              # waits; prints approve, reject or the written reply, then acks
ntf ack <request id> "Restarted, all good"    # a later note on that question
ntf read --since 1h --no-agent --download ./inbox

ntf ask exits 0 when answered, 3 when rejected and 4 when it times out (1 on an error, 2 on bad usage); --timeout sets the wait in seconds (default 600), --button 'Label=answer' offers other answers and --json prints the result as JSON. It uses the same protocol as sections 3 and 4: button answers go to the -answers topic with a fresh request ID, and written replies are messages on the main topic without the agent tag; it skips one tagged re- for another question, and --no-reply tags the question no-reply. Every message it sends is tagged agent. --server or NTF_SERVER points it at any ntfy server, including your own; --token or --user name:password signs in where a server needs it. ntf --help lists the rest.

Skill, AGENTS.md block and MCP server

ntf setup installs an ntf-ai skill into the agent skill folders it finds (~/.claude/skills, ~/.codex/skills, ~/.agents/skills), so your agent knows how to notify you and ask you questions. ntf setup --agents-file AGENTS.md also adds a short marked block to that file. It prints what it will write and asks before changing anything; ntf setup --remove takes it out again. ntf skill and ntf snippet print the two texts if you would rather paste them yourself.

For agents that use MCP, ntf mcp is a stdio MCP server with notify, ask, ack, subscribe_link, status and withdraw tools; notify and ask take an optional attach file path or URL. It reads the topic saved by ntf topic new --save. In Claude Code:

claude mcp add ntf-ai -- ntf mcp

Other MCP clients start it the same way: command ntf, argument mcp.

A prompt to give your agent

Set up phone notifications using https://ntf-ai.app/docs/agents. Generate a long random main topic, keep it local, and give me only that subscribe link. Wait for me to confirm receipt of a test notification. Notify me when work finishes or needs my input. Never subscribe my phone to the main topic's -answers topic. Tag every message you publish to the main topic agent, including status hooks. For decisions, send clearly worded Approve/Reject HTTP actions that post a unique request ID to the separate -answers topic, then poll that topic for the matching answer with a timeout. Save the question's published message ID. I can write back in the app, in the reply box on your question (NTF-AI 1.26 and later) or from the topic's compose sheet; either way it is a plain message on the main topic. From NTF-AI 1.26 a reply from the question's page carries the tag re-. Read since its Unix publish time minus one second and treat later messages without the agent tag as written replies, skipping one tagged re- with another question's ID. If only a button counts, tag the question no-reply. Keep one question outstanding, deduplicate processed message IDs, and never infer approval from a timeout. When you get an answer, ack it: post a short note to the main topic with the question's sequence ID, tags agent,ack and priority 1. If you stop without an answer, publish an update with that sequence ID, no buttons and one line saying you stopped waiting, or delete the sequence; never use a clear for this. Only put HTTP buttons on questions you are waiting on. Tell me my own written reply can notify my phone too. Treat replies and tags as unverified, keep the coding tool's permission rules, and never publish topic URLs or send conversation transcripts.

Answer a protocol v2 question

On NTF-AI 1.26 this question arrives with a hint and Answer/Reply buttons. Tap an answer button, or tap Reply and type your answer. Native controls for it come with NTF-AI 1.27: update when it is out. The fragment on this guide link carries the question schema; the fragment is not sent to the web server.

Question types

From NTF-AI 1.27 and ntf 0.4.0, use a choice for a fixed set of answers, a number for a bounded quantity, a date for scheduling, text for a short string, or a form for 1-6 related fields. Simple single choices with at most 3 options keep the 0.3.0 wire bytes. Other questions carry compact JSON in the fragment #ask-v2= of an "Answer in NTF-AI" action. Older clients get buttons or a Reply link plus a readable body hint. From NTF-AI 1.26 the ordinary reply box continues to work; native controls require 1.27.

ntf ask --button Staging=staging --choice 'Production!=prod' 'Deploy where?'
ntf ask --choice Logs=logs --choice Metrics=metrics --choice Traces=traces --multi 'Collect what?'
ntf ask --spec '{"kind":"number","min":1,"max":64,"step":0.5,"unit":"GB"}' 'Memory?'
ntf ask --spec '{"kind":"date","mode":"date","min":"2026-11-15","max":"2026-12-31"}' 'Which day?'
ntf ask --spec '{"kind":"text","max":60,"placeholder":"Branch name"}' 'Which branch?'
ntf ask --spec '{"kind":"form","fields":[{"k":"branch","kind":"text","l":"Branch","max":60},{"k":"n","kind":"number","l":"Replicas","min":1,"max":5}]}' 'Deploy settings?'
ntf ask --expires 2h --remind 5m,15m --escalate --as deploy-bot --avatar https://example.com/deploy-bot.png 'Proceed?'
ntf status <request id> --json
ntf status <request id> --wait --timeout 600
ntf withdraw <request id>

--button (or -b) and --choice are the same option: LABEL[=ANSWER], repeated for 2-12 choices. Without =ANSWER, the label becomes a lowercase key with spaces replaced by hyphens. Up to 3 choices use the original buttons; more use the native picker. Labels ending in ! are literal. --multi allows several selections. For constraints or other kinds use --spec JSON, or --spec @question.json. It accepts the wire schema object (v defaults to 2): kind is choice, number, date, text or form. No additional schema flags are needed. For multi-select, use {"kind":"choice","multi":true,"options":[{"k":"a","l":"A"},{"k":"b","l":"B"}]}; multi is not a kind.

A choice spec has options:[{"k":"go","l":"Go!","d":true},{"k":"stop","l":"Stop"}]; d:true alone marks a destructive choice. multi:true enables selection-count min/max. Number bounds are inclusive; step defaults to 1 from min (or zero), and unit is display only (12 characters). Date mode is date (YYYY-MM-DD), time (HH:MM) or datetime (default, RFC 3339 with an offset); bounds use the same format. Text max is 1-1000 characters (default 200); placeholder is at most 60. A form's fields array has 1-6 objects with k, l, kind and the corresponding kind constraints, plus opt:true for optional fields. Nested forms and multi-choice fields are not supported. Schemas are limited to 1536 UTF-8 bytes; option/field labels to 40 characters.

Free replies keep the NTF-AI 1.26 behavior. The 1.27 app sends structured answers on the main topic with tags re-<request id>,ans. Without ans the result stays kind: reply. --json returns the raw answer, normalized value, type, valid, authenticated, and reply_to for tagged replies. Free replies accept option keys, labels (case-insensitive) or 1-based numbers; multi choice numbers are comma-separated. Number answers use a dot, dates use ISO format, and forms accept a JSON object or one Label: value line per field. Invalid JSON results retain valid: false. Plain output retains the raw answer, warns on stderr and exits 6; --strict keeps waiting instead. From ntf 0.4.0, plain output and the MCP text print a valid typed answer the way the 1.27 answer form sends it (the choice key, keys comma-separated, the number, date or text, a form as compact JSON), whichever app answered. When a written reply answered a typed question (NTF-AI before 1.27, or another ntfy app), stderr says so and how it was read, e.g. read '2' as 'staging'; under --json that answer is kind: reply. --no-reply removes the fallback reply link and ignores free replies, while native structured answers still work; it warns for free-form kinds because older clients then have no answer path. Exit 5 means withdrawn; existing exit codes remain 0 answered, 3 rejected, 4 timed out, 1 error, 2 usage.

Deadlines, reminders, withdraw

--expires accepts 60s to 7d and caps the wait at the schema's exp deadline. A timeout still settles at priority 1 with no actions. --remind accepts at most 3 offsets at least 5 minutes apart, such as 5m,15m. While the agent keeps waiting, it republishes the same sequence/body with increasing rem; --escalate raises priority by one per reminder, capped at 4 (an explicit 5 stays 5). From NTF-AI 1.27 the app can alert for these reminders; older apps keep updates silent. --no-wait publishes and prints the request id (JSON returns pending), with no background reminders; use status to read the answer later.

Read back a question (`ntf status`)

ntf status folds linked server events into withdrawn, acked, answered, settled, expired, seen, pending or unknown (in that precedence). Seen means read or dismissed on some device, not proof a person read it. A clear (message_clear) records that observation; ntf withdraw sends DELETE and produces message_delete. A withdrawn plain ask explains why it stopped on stderr. Status polls from the publication's server Unix timestamp, so local clock skew and an expired question row cannot hide answers. asks.jsonl, next to the config, is mode 600, pruned at 30 days, and stores schemas, request metadata and observed outcomes. Answer text is stored only for plain topics; encrypted asks save outcome state and timestamps without the answer. A write failure warns and the ask keeps waiting. Without server caching, untagged legacy replies in the poll/publish window are ambiguous; use replies tagged re-<request id> (from NTF-AI 1.26) when questions overlap. ntf status --topic TOPIC <request id> works without a ledger; its answers have valid: null. Keep the ledger private.

Question bodies and ordinary messages expire after 12 hours; protocol answers and receipts are kept 8 days on servers advertising agent_retention_seconds: 691200. Older servers default to 12 hours. Past advertised retention, status reports unknown unless it has an observed outcome or linked server evidence. It reads agent_retention_seconds when advertised; this CLI does not change server retention.

Agent name and picture

--as uses the flag, NTF_AGENT, then config agent_name; names are 1-32 letters, digits, spaces, periods, underscores or hyphens. --avatar carries an https URL as ntfy icon. Plain-topic names, icons and answers can be forged by anyone who knows the topic. Plain answers report authenticated: false.

MCP ask accepts kind, options (k, l, optional d), multi, min, max, step, unit, mode, fields, placeholder, expires, remind, escalate, as, avatar, strict and wait. With wait:false it returns pending immediately. The MCP tools are notify, ask, ack, subscribe_link, status and withdraw; status accepts request_id, wait, timeout_seconds, and withdraw accepts request_id.

End-to-end encryption with ntf

Set the same topic password in the app and in the shell running ntf. No packages or extra service are needed:

# Load the password from your secret manager, or enter it without putting it in shell history:
export NTF_TOPIC_PASSWORD="$(python3 -c 'import getpass; print(getpass.getpass("Topic password: "))')"
ntf send 'Private build result'
ntf ask --spec '{"kind":"number","min":1,"max":64,"unit":"GB"}' 'Memory?'

NTF_TOPIC_PASSWORD enables encryption for send, questions, reminders, settles and acknowledgements, and decrypts read, listen, ask and status. MCP inherits it from its process environment too. --password-env VAR chooses another environment variable; --password-file PATH reads a UTF-8 file, trimming only trailing newlines. Password values never go in command arguments. Keep the password file private. Config "topics":{"TOPIC":{"e2e":true}} requires a password for that topic, so a missing secret fails before publishing. The private ledger stores metadata and schemas, but omits observed answer text for encrypted asks.

The format matches NTF-AI 1.26 and later: AES-256-GCM compact JWE, PBKDF2-HMAC-SHA256 with 50,000 rounds, and a random 12-byte IV. The bare public alias on its standard HTTP/HTTPS port derives with https://ntfy-me.com/<topic>. Other server URLs use the exact spelling stored in the app (including host case and any path or custom port), without trailing slashes; use the same spelling in both clients. Message, title, tags, priority, links, icon, Markdown and actions are encrypted together. The outer topic, sequence id and protocol tags (agent,ack, re-<id>,ans) remain visible for routing and retention; authenticated inner tags are trusted. Ciphertext must be under 4096 bytes. Attachments, including --attach-url, are refused before network activity.

Legacy HTTP buttons stay inside the encrypted question for NTF-AI 1.26. They post plaintext answer keys to <topic>-answers; those answers report authenticated: false. --e2e-strict omits the buttons and sends a native schema even for Approve/Reject. Successfully decrypted native replies report authenticated: true: they prove knowledge of the shared password, not a person's identity. Wrong-password or damaged ciphertext is skipped with an immediate one-time stderr warning; ask/status JSON includes undecryptable, and read/listen reports the count on stderr.

From ntf 0.4.1, an encrypted answer is authenticated: true only when its encrypted payload carries re-<request id> and the server received it no earlier than the question, so an old encrypted reply cannot be replayed into a new ask. NTF-AI 1.26 and 1.27 both encrypt that tag (replies typed on the question's page, and 1.27 answer-form answers); compose-sheet replies have no tag and report authenticated: false. With --e2e-strict, or a topic configured e2e, an unauthenticated answer never answers: ask keeps waiting and status ignores it. Otherwise plain ask prints it on an encrypted topic, warns on stderr and exits 7 (unauthenticated answer); --json keeps exit 0 with authenticated: false. Plain output escapes control characters in messages, titles, tags, answers and attachment links as \xNN; JSON is unchanged. From ntf 0.4.2, the same ciphertext posted again (a replay, matched on its IV, tag and ciphertext bytes; encodings with another spelling are refused) is skipped with a one-time stderr warning, so the first copy wins. The first authenticated answer to a question wins, and an authenticated answer saved in the ledger is final: no later event replaces it, even in another process after the original aged out. An attachment outside the ciphertext is dropped from a decrypted message, and under strict mode status ignores a saved answer the ledger does not record as authenticated (the ledger keeps answer_authenticated and answer_message_id, never encrypted answer text).

What's new for agents

Newest first. Each entry says what an agent can now rely on and which version brought it.

Claude Code recipe

The current Claude Code hook reference defines Stop when a response finishes and Notification with matchers such as permission_prompt and idle_prompt. Command hooks receive JSON on stdin. The following helper sends only a fixed status, not tool inputs, paths or transcript text.

Codex recipe

The current Codex notification documentation defines notify as an external command receiving one JSON argument, currently for agent-turn-complete. This does not send approval requests. Put notify at the top level of the user ~/.codex/config.toml; project-local config cannot set it. The configuration reference explains that scope.

Install the small status helper

These recipes are for locally run command-line agents that inherit NTF_AI_TOPIC from the terminal above. Set it to your saved topic in each new terminal before starting the tool. Save this helper in the current directory; it uses only Python's standard library.

cat > ntf-ai-notify.py <<'PYCODE'
import json, os, re, sys, urllib.request
mode = sys.argv[1]
if mode == 'claude':
    event = json.load(sys.stdin)
    hook = event.get('hook_event_name')
    if hook == 'Stop':
        message = 'Claude Code finished a response.'
    elif hook == 'Notification' and event.get('notification_type') in ('permission_prompt', 'idle_prompt'):
        message = 'Claude Code needs your attention.'
    else:
        raise SystemExit(0)
elif mode == 'codex':
    event = json.loads(sys.argv[2])
    if event.get('type') != 'agent-turn-complete':
        raise SystemExit(0)
    message = 'Codex finished a turn.'
else:
    raise SystemExit('Use claude or codex')
topic = os.environ['NTF_AI_TOPIC']
if not re.fullmatch(r'[A-Za-z0-9_-]{1,64}', topic):
    raise SystemExit('Invalid topic')
request = urllib.request.Request('https://ntf-ai.app/' + topic,
    data=message.encode('utf-8'), method='POST', headers={'Content-Type': 'text/plain', 'Tags': 'agent'})
with urllib.request.urlopen(request, timeout=10) as response:
    print(response.read().decode())
PYCODE
python3 - <<'PYCODE'
from pathlib import Path
import json, shlex
helper = str(Path('ntf-ai-notify.py').resolve())
command = shlex.join(['python3', helper, 'claude'])
settings = {'hooks': {
    'Stop': [{'hooks': [{'type': 'command', 'command': command}]}],
    'Notification': [{'matcher': 'permission_prompt|idle_prompt',
                      'hooks': [{'type': 'command', 'command': command}]}]}}
Path('ntf-ai-claude-settings.json').write_text(json.dumps(settings, indent=2)+'\n')
Path('ntf-ai-codex-config.toml').write_text('notify = '+json.dumps(['python3', helper, 'codex'])+'\n')
print('Merge ntf-ai-claude-settings.json into your existing ~/.claude/settings.json hooks.')
print('Merge ntf-ai-codex-config.toml at the top level of ~/.codex/config.toml.')
PYCODE

Merge these snippets with existing settings; do not replace other hooks or an existing notify command blindly. Start a new tool session from the terminal with NTF_AI_TOPIC exported. Remove the hook entries or notify line to turn notifications off. These status hooks alert you; the ask-and-answer protocol above is something you instruct the agent to run explicitly.

Check the helpers before configuring either tool, using representative documented event payloads. These commands send real messages to your test topic:

printf '%s\n' '{"hook_event_name":"Stop"}' | python3 ntf-ai-notify.py claude
printf '%s\n' '{"hook_event_name":"Notification","notification_type":"permission_prompt"}' | python3 ntf-ai-notify.py claude
printf '%s\n' '{"hook_event_name":"Notification","notification_type":"idle_prompt"}' | python3 ntf-ai-notify.py claude
python3 ntf-ai-notify.py codex '{"type":"agent-turn-complete"}'

Documentation checked 2026-11-05. Helper payload tests do not prove either tool ran a live hook, or that a phone received a push. The guide's live protocol check used a throwaway topic, simulated the button POST and the written-message POST, and read both answers back. The app subscription confirmation and compose paths are separate app checks. Works with stock ntfy HTTP publishing and polling; no custom server extension is required for these recipes. Server compatibility and push delivery explains the ntfy.sh banner limit.

Opening this page does not send an answer. If a notification's reply link brought you here, ask your agent for the destination topic URL. Subscribe to that topic in the app and use its compose sheet to write back. A reply link is a client instruction, not a stock ntfy HTTP action that posts an answer. Do not assume every ntfy client implements the same reply interaction. The HTTP action-button recipe above works without that interaction.

Protocol v2 schema and curl

| kind | Controls | Answer body | |---|---|---| | choice | options of k/l/d, multi and min/max counts | keys comma-joined in option order | | number | inclusive min/max, step, unit | decimal with dot | | date | mode date/time/datetime, ISO min/max | ISO string, offset for datetime | | text | max, placeholder | trimmed text | | form | 1-6 fields: k/l/kind, opt and constraints above | compact JSON object, numeric values as numbers |

All schemas require v=2 and kind; exp is Unix seconds, reply a boolean, hint the exact appended body hint, rem a counter from 1 to 3. Unknown keys are ignored. Unknown versions or kinds fall back to old controls.

python3 - <<'PYCODE' > ntf-ai-v2-question.json
import base64, json, os
schema = {'v': 2, 'kind': 'text', 'max': 60, 'reply': True}
encoded = base64.urlsafe_b64encode(json.dumps(schema, separators=(',', ':')).encode()).decode().rstrip('=')
print(json.dumps({'topic': os.environ['NTF_AI_TOPIC'], 'sequence_id': os.environ['NTF_AI_REQUEST'],
    'tags': ['agent'], 'message': 'Which branch?', 'actions': [
        {'action': 'view', 'label': 'Answer in NTF-AI', 'clear': False,
         'url': 'https://ntf-ai.app/docs/agents#ask-v2=' + encoded},
        {'action': 'view', 'label': 'Reply', 'clear': False,
         'url': 'https://ntf-ai.app/docs/agents#reply-v1=https%3A%2F%2Fntf-ai.app%2F' + os.environ['NTF_AI_TOPIC']}]}))
PYCODE
curl -H 'Content-Type: application/json' --data-binary @ntf-ai-v2-question.json https://ntf-ai.app