Human
What you do on the iPhone
The human side takes about two minutes. You authorize the connection and describe the result you want; you never need to paste a long-lived token into chat.
- 01
Open Bellwire
Sign in with Apple, allow notifications, and optionally create the Demo project to verify that the app can display a card and Event.
- 02
Choose one useful signal
Name the current state you want visible and the moments that deserve a notification—for example deployment status, daily revenue, or an Agent waiting for approval.
- 03
Generate a binding code
Open Settings → Agent connections → Generate binding code. The six-digit code is single-use and expires after 10 minutes.
- 04
Give the code to your Agent
Use the handoff prompt below. If the code expires before it is claimed, generate a new one; do not reuse an old code.
- 05
Review sensitive choices
New projects start Private. If the Agent requests Hosted, Bellwire will ask you to approve it in the app before any project content can be stored in Bellwire Cloud.
Handoff
Give your Agent one precise instruction
Enter the temporary code and customize the state and Event you care about. The code stays in this browser tab and is only placed in the copied prompt.
Use the Bellwire Skill to connect this repository with pairing code 123456. Show the project state that matters and notify me at important completion, failure, recovery, or decision points. Keep the project Private unless I explicitly approve Hosted. Put runtime credentials only in the project's real secret manager, test the integration, deploy it, and complete one real end-to-end verification before calling it production verified.
Agent Skill installation
Agents that do not already have the Bellwire Skill can install it from ClawHub or read the complete Skill from GitHub.
clawhub install @xwchris/bellwireAgent
What the Agent must complete
Binding is only authorization. A production integration also needs source-side code, runtime secrets, deployment, and a real operation that proves the path.
- 01
Install and read the Skill
Use the complete Bellwire Skill, including its references and scripts. The Skill defines security boundaries, payloads, tests, and completion language.
- 02
Exchange the binding code
Claim the one-time code for a scoped Agent token. Store the returned token outside tracked files and never print it in commits, screenshots, or logs.
- 03
Inspect before creating
Understand the repository, existing secrets, deployment target, and real post-commit trigger. Reuse an existing Bellwire project instead of creating duplicates.
- 04
Implement the selected data path
Private requires signed Direct v2 endpoints, an opaque-reference outbox, and a wake-only token. Hosted requires a user-approved mode change, schemas, and a project-scoped Ingest Token.
- 05
Integrate at the source of truth
Send only after the real business transaction commits. Use a stable idempotency key and avoid turning notification failure into business-operation failure.
- 06
Test, deploy, and verify
Run focused tests, configure the real runtime secret, deploy the adapter, then observe one genuine payment, deployment, job, or other source operation.
Data path
Choose the data path deliberately
Private and Hosted are not quality levels. They are different data paths with different storage and integration tradeoffs.
Private — default
Bellwire receives only an opaque wake. Your iPhone fetches notification, Inbox, and Surface details directly from your signed HTTPS service. Details are cached on that iPhone for up to 30 days and are cleared when you sign out.
Best for customer-derived, operational, or sensitive project content—and teams willing to implement the Direct endpoints.Hosted — user approved
Bellwire Cloud stores Event, Inbox, Surface, and delivery details and handles the simpler ingestion path. Free keeps Hosted history for 7 days; Pro keeps it for 90 days.
Best for the quickest integration, durable cross-device history, and content you are comfortable storing in Bellwire Cloud.An Agent can request Hosted, but cannot approve it. Only the signed-in person can approve the change in the iOS app.
Verification
Do not stop at a test Event
A green API response proves configuration, not the production loop. Use this checklist before you rely on Bellwire.
- A real source operation reached the intended post-commit trigger.
- The deployed runtime—not only the local shell—has the correct project ID and project-scoped token.
- Retrying the same source operation does not create a duplicate Event or wake.
- Private: the outbox reference, wake, signed iPhone fetch, and local result all succeeded without content entering Bellwire Cloud.
- Hosted: the Event or Surface appears with the expected data and its delivery detail is readable.
- APNs acceptance is reported separately from confirmation that the notification appeared on the iPhone.
Configured
Project, credentials, or a manual test exists.
Integrated
Source code, deployment, and runtime secrets exist; a real operation is still unverified.
Production verified
A real source operation completed the entire path and the result was checked.
Troubleshooting
If a project or Event is missing
Check the data path first, then determine whether the failure is in configuration, runtime delivery, or app refresh.
Project does not appear
Generate a fresh binding code, verify the Agent is connected to the same Apple account, and ask it to list existing projects before creating another one.
Hosted Event is missing
Check the active schema, deployed Ingest Token, idempotency key, quota response, and the exact post-commit code path. Free Hosted history is deleted after 7 days; Pro after 90 days.
Private Event is missing
Check Direct readiness, the opaque reference outbox, wake acceptance, signed request verification, and the iPhone's last local sync. Signing out clears Private history on that device.
Notification is missing
Check iOS permission, device registration, APNs environment, delivery detail, and whether APNs only accepted the request without presenting it.