← Writing a plugin
Extend kcode
Send a notification to your phone
Let the agent send a requested update to your ntfy topic. The Lua tool checks the message, sends it with kcode.fetch, and reports server acceptance, not proof of phone delivery.
The manifest grants net.http and supplies endpoint and topic settings. The Lua file registers send_notification and sends the literal message text as the request body, with no shell and nothing to quote. A kcode Lua-runtime test checks the POST with a stand-in for kcode.fetch. The tool runs when the agent calls it; the README names the events a plugin watches to alert you instead.
ntfy-notify/README.md
# Send a remote notification
This Lua plugin adds `send_notification`, a tool that sends a message to an ntfy topic with `kcode.fetch`. The agent calls it when you ask to be told about something, such as "notify me when the build finishes". It is not an alert: nothing is sent on its own when the agent waits on you or a turn fails.
## Install and configure
Copy `plugin.toml` and `main.lua` into `<project>/.kcode/plugins/ntfy-notify/`. Configure the server and topic in your kcode configuration:
```toml
[plugins.ntfy-notify]
endpoint = "https://ntfy.sh"
topic = "your-chosen-topic"
```
A session opened after you save the file uses the table; no restart is needed. A value kcode can't use is named in `/plugins` and by `kcode doctor`, and the setting keeps its default.
Subscribe to that topic in your ntfy client. No topic is configured by default, so accidental calls cannot send to a shared example topic. Public ntfy topics are not private: do not send secrets or confidential project details. This small example does not implement authentication; use an appropriate trusted endpoint and do not put credentials into the URL.
`kcode.fetch` reaches any public host. A self-hosted ntfy server on your network or on this Mac is reached only when the manifest's `net.http` list names its host, such as `"net.http" = ["ntfy.home.lan"]`.
```json
{"title":"Build finished","message":"The requested checks passed"}
```
The tool checks the title, topic and message size, sends a POST, and checks that the server accepted it. It returns `accepted`, `http_status`, and `delivery_confirmed: false`. HTTP acceptance is not proof of delivery to a phone. A failed send is not retried; check the failure before retrying, because a request that timed out may already have arrived.
## How the files cooperate
`plugin.toml` grants `net.http` and declares typed server and topic settings. `main.lua` registers the tool, checks its input, and sends the message bytes as the request body and the title as the `Title` header. No shell or curl is involved, so there is nothing to quote and no permission card for each send.
## An alert instead of a tool
To be told whenever kcode needs you, watch events rather than wait for the agent to call a tool. `core.app.waits-changed` fires when a permission card or a question opens or closes, and `core.app.turn-error` when a turn fails. A plugin with the `hooks` and `net.http` grants can watch both with `kcode.on` and send the same request from its handler.
## Verification
The kcode repository contains an opt-in test. It loads this plugin in the Lua runtime with a stand-in for `kcode.fetch`, so nothing leaves the machine, and checks the method, URL, title, literal message bytes, acceptance reporting, the refusal of a title with a line break, and the error for a refused message.
```sh
KCODE_NTFY_PLUGIN_DIR=/absolute/path/to/ntfy-notify cargo test -p plugin-runtime-lua --test ntfy -- --ignored
```
Phone delivery must be checked separately with your chosen server and topic.ntfy-notify/plugin.toml
name = "ntfy-notify"
version = "0.2.0"
description = "Send a notification to a configured ntfy topic"
kind = "Lua"
[capabilities]
# Public hosts need no entry; add a self-hosted server on your network here.
"net.http" = []
[settings.endpoint]
type = "string"
default = "https://ntfy.sh"
description = "ntfy server base URL; HTTPS required"
[settings.topic]
type = "string"
default = ""
description = "Your ntfy topic; configure before sending. Public topics are not private"ntfy-notify/main.lua
kcode.register_tool("send_notification", "Send a message to the user's configured ntfy topic. Use only when the user asked to be notified. Returns server acceptance, not proof of phone delivery. Do not include secrets.", function(args)
local endpoint = kcode.settings.get("endpoint"):gsub("/+$", "")
local topic = kcode.settings.get("topic")
assert(type(topic) == "string" and #topic > 0 and #topic <= 128 and topic:match("^[%w_-]+$"), "configure a topic containing letters, digits, underscores or hyphens")
assert(endpoint:match("^https://[%w%.%-]+:?%d*$"), "endpoint must be an HTTPS server origin")
local message = args.message
assert(type(message) == "string" and #message > 0 and #message <= 4096, "message must contain 1 to 4096 bytes")
local title = args.title or "kcode"
assert(type(title) == "string" and #title > 0 and #title <= 120 and not title:find("%c"), "title must contain 1 to 120 bytes without control characters")
local response = kcode.fetch({
url = endpoint .. "/" .. topic,
method = "POST",
headers = { Title = title },
body = message,
})
assert(response.status >= 200 and response.status < 300, "ntfy did not accept the notification: HTTP " .. response.status)
return { accepted = true, http_status = response.status, delivery_confirmed = false }
end, { schema = {
type = "object", properties = {
message = { type = "string", description = "Notification text; no secrets" },
title = { type = "string", description = "Optional title, default kcode" },
}, required = { "message" }, additionalProperties = false,
}, read_only = false })