Using AgentDock
Notifications
In-app and Telegram alerts, rules and mutes.
AgentDock tells you when something needs a person: a blocked worker, a permission prompt, a pull request waiting for approval, a runner that dropped, a budget that ran out. Notifications arrive in the app and, if you link it, in a private Telegram chat.
Kinds
| Kind | When | In-app | Telegram | Who gets it |
|---|---|---|---|---|
person.needed | The orchestrator says it needs a person | on | on | Project members |
slot.blocked | A worker checkpoints as blocked, or an issue is blocked on a person | on | on | Project members |
pane.prompt | A worker's pane shows a prompt or dialog | on | on | Project members |
quota.hit | A worker's pane shows the usage limit banner | on | on | Project members |
queue.dry | A round found no ready issue and no slot is running (at most once per project per 6 hours) | on | off | Project members |
pr.awaiting_approval | A green pull request waits for merge approval | on | on (off for viewers) | Project members |
runner.offline | A runner has been offline for more than 5 minutes | on | on | Admins |
runner.online | That runner is back (closes the incident) | on | not available | Admins |
budget.threshold | A budget crossed a threshold below 100% | on | on | See budgets |
budget.exceeded | A budget reached 100% | on | on | See budgets |
schedule.disabled | A schedule turned itself off | on | on | Admins |
The In-app and Telegram columns are the defaults. You change them per kind (see Rules). Admins count as members of every project. Disabled and pending accounts get nothing.
pr.awaiting_approval depends on the Code Sentinel plugin announcing the wait; see Merge approvals.
In-app centre
The bell in the header shows your unread count and updates live. Account → Notifications lists everything newest first, with an unread filter and Mark all read. Each item links to the page where you act on it.
Link Telegram
An admin first connects a bot under Admin → Integrations → Telegram. See Telegram for creating the bot. Then each person links their own chat:
Start the link
Go to Account → Notifications and click Link Telegram. AgentDock creates a one-time code (valid 10 minutes, single use) and gives you a
https://t.me/<bot>?start=<code>link.Open it in Telegram
Open the link and press Start. The bot receives
/start <code>and binds your private chat to your account. Group chats are refused, and a chat can belong to one account only.Check the card
The Telegram card now shows your linked chat. Unlink in the card, or
/stopin the chat, removes the link.
The bot uses long polling, so your AgentDock server needs only outbound HTTPS to api.telegram.org. No public URL or webhook is required.
Rules
The Rules table on Account → Notifications has one row per kind with an In-app and a Telegram switch. A kind you never touched uses the defaults above. The Telegram column links to the link card until you have linked a chat. You only see kinds your role can receive.
Muted projects
Muted projects silences every project kind for one project, on both channels, either until a date or until you remove the mute. Muted items are still recorded in the in-app list but do not count as unread. Admin kinds such as runner.offline are not affected by project mutes.
Folding and limits
- Folding. The same kind for the same project and slot within 15 minutes is folded into the existing notification, which shows a count, instead of creating a new one.
- Telegram cap. At most 20 Telegram messages per person per 10 minutes. Beyond that, items are collected into a single digest sent at the end of the window.
- Rate limits from Telegram (HTTP 429) are respected.
What a message contains
A notification is a short plain-text summary: the kind, the project, the slot or issue, a one-line reason, and a link back to AgentDock (built from APP_URL).
Messages never include pane text, prompts, code or secrets. This matters for Telegram in particular, which is a third-party service. To see what a worker is doing, follow the link and open the live pane.
A pr.awaiting_approval message on Telegram also carries Approve and Request changes buttons for operators and admins of the project. See Merge approvals.
Runner offline
A watcher checks runner status every 60 seconds. A runner that has been offline (or stale) for more than 5 minutes opens one incident and sends one runner.offline to admins. When it comes back, a runner.online item closes the incident in the app only, without a Telegram message. There is at most one open incident per runner, so a flapping runner does not flood you.
If a runner stays offline, check it on its machine with agentdock-runner status and its log. See Runner reference.