Channels and signals
Talk to sedge from Telegram or Slack, and wake it when something happens elsewhere.
- A channel is a conversation between you and sedge: Telegram, Slack, or whatever else you can imagine. Your messages wake it; its answers and questions come back there.
- A signal is something happening elsewhere: CI failed, a feed changed, a price moved. It wakes sedge with your instruction for what to do then.
Both are connected the same way, and both come in kinds that packages provide.
Connect one
Ask in the TUI, in your own words:
set up telegram
tell me when the CI on main fails
sedge finds or installs the kind, shows you what it will connect, and asks for any secret
(a token, a password) in a hidden field. Secrets go to your OS keychain (macOS Keychain,
libsecret on Linux, Windows Credential Manager); the config file only names them. Where there's
no keychain, an owner-only file in ~/.sedge stands in.
The tools it uses, if you want to ask for them by name: channels, signals,
find_packages, install, uninstall, connect and update_signal (with filters, windows,
triage and labels), disconnect, invite,
create_signal. See Commands.
Pairing a channel
A channel answers only accounts you paired. Connecting one gives you an invite with a one-time
code: on Telegram a link (https://t.me/<your bot>?start=<code>) to open on your phone; on Slack
a message to send the bot (pair <code>). That account is paired, and the code is spent. Codes expire after 30 minutes. Anyone else who writes to your
bot, with or without a code, gets no answer at all.
To pair another account, or after a link expired, ask for a new invite (invite tool).
What a channel can do
- Typing: while sedge works on your message, the channel shows it (Telegram's "typing…").
- Formatting: messages are Markdown, rendered as far as the channel can.
- Choices: a message can carry buttons. Your pick comes back to sedge as an event. Approvals use this: Approve / Deny.
- Files: sedge can attach files from your machine.
Answers go to the channel and chat you last wrote from.
Models
Send /model on a channel to see which model its messages run on, with a button for each model
you're logged in to. /model opus picks one by name, /model opus medium (or opus:medium) also
sets how hard it thinks, and /model high changes only that. It applies from your next message, and
nothing goes to the agent. A signal can have its own model too: ask the TUI's agent ("triage CI on
Haiku, answer it on Opus") or set model on the connection. See
Configuration.
Signals
A signal reports what happened as data, never as instructions: text inside a CI log that says
"ignore your instructions" stays text. sedge reads the event together with the instruction you
gave when connecting it ("tell me if it's my commit", "retry once, then tell me"). Signals report
into the main conversation, so a follow-up question on Telegram has the context, unless you gave
the signal to another agent.
Filtering, throttling and triage
A signal can fire more than you care about. These settings on any signal decide what reaches the agent, so a noisy one doesn't start a model run for each event. They apply in this order:
match: only events whose text or details match this regular expression (any case), likefail|error.ignore: drop events whose text or details match this one, likedependabot.when: only events whose details meet a condition, written the way you'd say it:temperature > 30 and room = kitchen,payload.moisture < 30,status != ok or retries >= 3. A field is a path into the details the signal reports (see Kinds);textis the event's text. Operators are=,!=,>,>=,<,<=andcontains;andbinds tighter thanor. A number sent as text still compares as a number, and an event without the field doesn't get through.throttle: after an event gets through, drop the next ones for this long (10m,1h): one message about the alarm, not one a minute. The time is kept, so a restart doesn't cut it short. A signal that checks on a schedule and keeps reporting the same thing (a CI failure still failing) reports it again once the window is over, so it's held back rather than lost.batch: hold events this long after the first (30s,5m,1h) and hand them over together, in one run. Held events are kept in the inbox, so a restart doesn't lose them, and anything else that wakes the same agent first takes them along.triage: before the events wake the agent, a cheap model reads them with your instruction and decides whether they need it. When it says no, the agent sleeps on and the inbox shows the events as skipped, with why ("Skipped by triage (openai/gpt-5-mini): the soil is still moist"). It costs one small call per event (or batch), far less than a run. It uses the cheapest priced model of your default model's provider (or one named like a small model, or your default), or the one you name intriageModel. When it isn't sure, or can't run, the agent wakes, so nothing is missed. Triage only decides for a run made entirely of events from signals withtriageon; when anything else wakes the same agent (your message, a timer, another signal), they're handled together, untriaged.labelsandwakeOn: triage also tags each event with one of your labels, and you decide by label instead of leaving it to the model. See Labels.
The rules (match, ignore, when) cost nothing and are exact; triage understands what you meant
("only if it's my commit") at a small price. Use the rules when you can say it as one, and triage
when you can't.
Say it when connecting ("tell me if the kitchen goes above 30, at most once an hour"), or change it
later ("stop telling me about dependabot"): the TUI's agent sets these with connect and
update_signal, and you confirm.
Labels
Give a signal a list of labels, and the cheap triage model picks one for each event: a camera's
motion as person, vehicle, animal or nothing, a support email as bug, billing or
spam. Labels turn triage on.
"porch": {
"kind": "webhook",
"instruction": "Tell me who's at the door.",
"labels": ["person", "vehicle", "animal", "nothing"],
"wakeOn": ["person", "vehicle"]
}- The agent reads each event with its label (
[porch · … · labelled person]), andsedge dashshows it in the inbox. - With
wakeOn, the labels decide: an event wakes the agent only if it's labelled one of them, and the rest are skipped ("labelled animal, not one that wakes it"). Without it, the model decides as usual and the label is there to read. - An event the model couldn't label (it answered with something not in your list) is left unlabelled and wakes the agent, so nothing is missed.
Labels are given at triage, after when and the other rules have run, so a condition can't use
them; wakeOn is the rule that does.
Named values
Some things are a state, not news: whether you're home, the house's mode, a sensor's latest
reading. Named values keep them, and any signal's when condition reads them as state.<name>:
"home-mode": { "kind": "mqtt", "settings": { "url": "mqtt://hub.local", "topics": ["home/mode"] },
"remember": "mode" },
"porch": { "kind": "webhook", "labels": ["person", "vehicle", "nothing"],
"wakeOn": ["person", "vehicle"], "when": "state.mode = away" }- A signal with
rememberkeeps its latest value under that name and never wakes the agent: an MQTT message'spayload, a webhook'sbody, otherwise its details or text. Itsmatch,ignoreandwhenstill decide which events count. - The daemon's agent sets them too (
set_state): say "I'm away till Sunday" and it can setmode = away, and set it back when you're home. A run woken by outside content can't: what someone else wrote doesn't get to decide what wakes the agent. It reads them withget_state. - Conditions read them like fields:
state.mode = away,state.soil < 30. A value that isn't set fails the clause, as a missing field does.
They're kept in sedge's store, so they survive restarts. The TUI's state tool lists them, with
who set each one and when. Names are letters, digits, - and _.
Permissions for what signals bring
A signal's events are outside content: someone else wrote them. A run they wake (and what it
passes on: a message to another agent, a subagent, a timer) asks before running commands, calling
MCP tools or writing files outside its own folder, unless you loosen permissions.signals. See
Runs woken by outside content.
Kinds
| Kind | Type | Package |
|---|---|---|
telegram | channel | @sedge-hq/telegram |
slack | channel | @sedge-hq/slack |
github-ci | signal | @sedge-hq/github: Actions runs that fail |
github | signal | @sedge-hq/github: reviews asked of you, assignments, mentions |
web-page | signal | @sedge-hq/web: a page whose text changes |
feed | signal | @sedge-hq/web: new posts on an RSS or Atom feed |
webhook | signal | @sedge-hq/local: HTTP POSTs to a local address |
files | signal | @sedge-hq/local: files created, changed or removed in a folder |
command | signal | @sedge-hq/local: what a shell command prints |
mqtt | signal | @sedge-hq/mqtt: messages on MQTT topics |
What each signal reports as details, for when conditions:
| Kind | Details |
|---|---|
github-ci | url, by (who pushed) |
github | url; pullRequest (true or false) for assignments |
web-page | url, removed (lines that went away) |
feed | url |
webhook | path, event (GitHub's event header, when sent), body |
mqtt | topic, payload |
files | none: use text, which lists what was created, changed and removed |
command | none: use text, the lines it printed |
Install a package with sedge install <name>: an official short name (telegram, slack,
github, web, local, mqtt) means @sedge-hq/<name>; anything else is an npm name as written,
or the path of a package folder. A folder is packed the way it would be published, along
with the workspace packages it depends on, so you can try a package before it's on npm.
To remove one, disconnect what uses it, then sedge uninstall <name>.
Webhooks, files and commands
@sedge-hq/local covers what happens on your machine or can reach it:
webhooklistens onhttp://127.0.0.1:4747(changeportandhost), and each POST is an event. Senders give the token you chose, asAuthorization: Bearer <token>, as?token=<token>, or as a GitHub webhook secret. A delivery id header (X-GitHub-Delivery,X-Request-Id,Idempotency-Key,Webhook-Id) drops a retried delivery. It only listens on this machine unless you sethost; to receive from outside, put a tunnel in front of it.fileslooks at a folder (or one file) everyseconds(default 10) and reports what was created, changed or removed, optionally only files matching apatternlike**/*.csv.commandruns a shell command. A long-running one (tail -n0 -f app.log,mosquitto_sub -t sensors/#) reports each burst of lines it prints, and is started again if it exits. Withminutes, it runs on a schedule instead and reports when its output changes (df -h /,systemctl is-active api). It runs in your home folder unless you setcwd. Anything a command can read becomes a signal this way: sensors, queues, MQTT topics, a service's status.
MQTT
Sensors, home hubs and devices often publish to an MQTT broker (Mosquitto, Home Assistant's,
EMQX, HiveMQ). The mqtt signal subscribes to the topics you give it, with + and #
wildcards (home/+/soil, sensors/#), and each message is an event: its topic, and what was
sent, with JSON laid out. The broker can be mqtt://, mqtts:// (TLS) or wss:// (WebSocket);
a password goes to the keychain like any secret.
Each message's details are its topic and payload, with JSON as values, so a condition can
read a field: payload.moisture < 30. It keeps a session on the broker, so messages sent at QoS 1
or 2 while sedge was stopped arrive when it's back (brokers don't keep QoS 0 messages). A topic's retained value, which brokers send again on
every subscribe, isn't reported. Sensors publish often, so a when and a throttle are usually
worth setting: "tell me when the basil's soil is dry, at most once an hour".
Slack
Slack connects with Socket Mode, so nothing has to be reachable from the internet. It needs a
Slack app of your own with two tokens; the
@sedge-hq/slack README walks
through making one in a few minutes. Then say "set up slack".
Community packages
Anyone can publish channels and signals. Ask sedge to look ("is there a Slack channel?") and it
searches npm for packages tagged sedge-kit (find_packages), showing who published each. Install
one by its npm name, or straight from a repository:
sedge install sedge-slack
sedge install github:someone/sedge-rssA community package's code runs inside the daemon with your rights, and sedge didn't write or
review it: install says so and links the package before you confirm. Read it first.
Your own
When nothing fits, ask sedge to write one: "make a signal for new issues in my repo". It writes a
module with @sedge-hq/kit, you review it, and create_signal registers it. Its code
runs inside the daemon with your rights, so read it before you say yes.