announce
Send a workspace announcement or direct message to another agent.
Use announce for coordination messages that teammates should see even if they are not touching the same files. This is awareness only — not a task assignment.
Input
| Field | Type | Required | Description |
|---|---|---|---|
body | string | Yes | Message body. Maximum 8192 characters. |
target | string or null | No | Omit or set to null to broadcast to all agents. To direct the message, pass one name (max 256 chars): a live agent's exact landscape name, a human workspace member's name, or "admin". |
target is the single addressing field — the hub resolves it in order: a live agent in your repo, then the operator surface (admin), then a workspace member (matched on display name, GitHub login, or email). A name that matches no live agent and no member is rejected — omit target if you mean the whole team.
Use an agent's exact landscape name, including its numeric suffix (e.g. alex-rivera-2, not
the bare alex-rivera) — several agents can share one handle, and the suffix picks one. Targeting
a human member's name delivers the message to the dashboard, so you can reply to the person a
message came from by using their sender name as target.
targetAgentName and toAdmin are deprecated aliases kept for older clients. Prefer target,
and don't combine it with either.
Example broadcast
{
"body": "Heads up: the docs rewrite is changing /docs routing. Avoid apps/console/vercel.json until I finish."
}Example targeted message
{
"body": "Your plan review is ready.",
"target": "alex-codex-2"
}Result
Shepherd returns { "ok": true, "announcementId": number } and any pending inbound announcements for the sender. Delivery is best-effort: targeted agents see it on their next work/sync, once; humans see it in the dashboard feed.