Start
Build with a coding agent
You don't have to write the endpoint yourself. A coding agent working in your project can read the format, write the endpoint, check it renders and give you a code to scan. You tell it what you want to see.
Add a GET endpoint to this project at /widget.json that returns a Webhook Widget view showing [what you want to see]. Follow the format and the good-practice rules at https://webhookwidget.com/llms.txt, check it renders in the headless playground, then give me the webhookwidget://register link and a QR code so I can add it on my phone.
Works with Claude Code, Codex and Cursor
Replace the part in brackets with what you want on your Home Screen, such as "today's sign-ups from our Postgres database" or "the result of the last GitHub Actions run on main". Run it in the project the data lives in, so the agent can reach it.
What the agent does
- Reads the format. llms.txt is written for agents: the payload contract, the nodes, the limits, and the practices that make a widget readable at a glance. The prompt points the agent there, so you don't have to explain any of it.
- Writes a GET endpoint in your project. It answers with JSON at
/widget.json. Every request says which size the phone is filling, so one endpoint can serve every size. - Checks it renders. The playground has a headless mode that draws the widget on its own, with the same engine the app uses, and reports anything that was cut off or left out. The agent looks at the result and fixes what it finds before you see it.
- Puts it where your phone can reach it. Your phone fetches the URL itself,
so it has to be HTTPS on the internet: not
localhost, and not a laptop on your Wi-Fi. If the project isn't deployed anywhere, the agent should say so and deploy it, or use the Cloudflare Workers starter. A tunnel from your laptop works for a first look, but the widget stops when the laptop sleeps. - Gives you a link and a QR code. It builds a
webhookwidget://registersetup link and draws it as a QR code in your terminal. Point your iPhone camera at it and Webhook Widget opens with the name, the address and any token filled in. Nothing is saved until you check them and tap Save.
The agent draws the code with the webhookwidget CLI, reading any token from an environment variable rather than the command line:
npx webhookwidget qr --name "Deploys" --url https://example.com/widget.json \
--auth bearer --secret-env WIDGET_TOKEN Then add the widget to your Home Screen, as in step 2 of the Quickstart.
Getting a good result
- Say what you want to see, and where it comes from. "Open pull requests waiting on my review, from GitHub" gives the agent something to fetch. "A dashboard" doesn't.
- Say the size. Tell it whether you'll use a small, medium or large widget.
One URL can serve all three, but the agent does a better job when it knows which one
you'll look at. It puts that size in the response as
preferredFamily, so the app previews the widget at that size and tells you which size to pick. - Ask for a token if the data is private. Anyone who has the URL can fetch it. Ask the agent to protect the endpoint; the token goes into the setup link, and the app sends it with every request. Authentication has the options.
- Change the server, not the phone. Ask for changes and redeploy. The widget follows the server, so there is nothing to reinstall: Fetch in the app shows the new version straight away, and the Home Screen catches up on its next refresh.
Next steps
- Quickstart: the same steps by hand, starting from an example URL.
- Examples: widgets with notes. You can name one to your agent: "make it look like the Server health example".
- Playground: paste what your agent wrote and see it at every size.
- llms.txt: what the agent reads.