Reference implementations for Shortcut Open Agents — the platform for building AI agent integrations that live inside a Shortcut workspace.
An agent app is a web service you own. Shortcut sends it signed webhooks when someone assigns it a story, @-mentions it, or replies to one of its comments, and the agent calls back into the Shortcut API to do the work. These demos are small, complete examples of that loop.
| Demo | Stack | What it shows |
|---|---|---|
quote-agent |
Cloudflare Workers + Hono | The full lifecycle: OAuth install, HMAC webhook verification, token refresh, and threaded comment replies. Posts a random programming quote whenever it's assigned or mentioned. |
guardian |
Cloudflare Workers + Hono | Enforcing a workspace rule from observer webhooks. Blocks stories from being started without a team: comments at whoever moved it, then moves it back. Shows how to reconstruct what changed from a payload that carries no diff, and how to avoid reacting to your own writes. |
- Open Agents overview — key concepts, webhook payload shapes, interaction triggers, and the app review lifecycle.
- Shortcut REST API — full API reference.
- Create an agent app in Shortcut under Settings → Developer. You'll get a client ID, client secret, and webhook secret.
- Stand up a service with two public endpoints — an OAuth redirect target and a webhook receiver — and register their URLs on the app.
- Install the app in a workspace from the integrations catalog and complete the OAuth flow.
- Verify the
Payload-Signatureheader (HMAC-SHA256 over the raw request body) on every delivery before acting on it.
quote-agent implements all four steps in about 450 lines; start there.
Each demo is self-contained in its own top-level directory with its own README and dependencies. Keep them small and focused on one idea — the point is to be readable end to end, not to be production-ready.
MIT — use these as a starting point for your own agents.