00Widget
Publish status cards and Live Activities to iOS widgets, the Lock Screen, and the Dynamic Island.
Open source Repository Open in the app JSON README (API)
About
Publish status cards and Live Activities to iOS widgets, the Lock Screen, and the Dynamic Island.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- com.00widget
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 1.0.0
- Open pull requests
- 5
- Last push
- 2026-09-04T16:47:17Z
- Repository state
- ativo
- Language
- TypeScript
- License
- NOASSERTION
- Added
- 2026-09-01 18:00:09
- Updated
- 2026-09-01 18:00:09
- Origin id
com.00widget/00widget
README
<p align="center"> <img src="./docs/brand/wordmark-horizontal.png" alt="00Widget — Widgets for all your agents." width="720"> </p> # 00Widget **Widgets for all your agents.** A reusable Apple-platform companion app and Cloudflare Worker backend that gives Claude, ChatGPT, automations, and software you build a native output channel through widgets, Live Activities, the Dynamic Island, and Apple TV dashboards. The server never sends UI — only structured state conforming to a small set of templates. The Apple apps render that state through predefined SwiftUI views. ## Choose how to connect ### Claude, ChatGPT, and other MCP hosts Hosts that speak the Model Context Protocol can publish to 00Widget with no integration code: add `<BASE_URL>/mcp` as a custom connector, sign in, and pick a tenant. The tools wrap the same handlers as the REST routes, so the two surfaces cannot drift. MCP is off by default (`MCP_ENABLED` in `wrangler.toml`) because it exposes a browser flow that mints API tokens on the public internet. Approving a connector requires signing in, and the credential it issues is a normal tenant token scoped to the approver's own account, revocable from `/admin`. Details: `server/README.md` → "MCP". ### Apps, scripts, automations, and coding agents If you're inside another repo (say, a CI pipeline or a home-automation script) and want to make Claude Code / Codex publish state to your 00Widget instance, paste this into the agent — it's self-contained: ``` Integrate this project with 00Widget so its state shows up on iOS widgets and Live Activities. Read the integration contract: https://github.com/morais/00widget/blob/main/docs/llms.md That single document is everything you need — don't pull in the rest of the 00Widget repo. Operator-supplied env vars: 00WIDGET_BASE_URL=https://api.example.com 00WIDGET_API_KEY=<bearer token> Verify both work with `curl $00WIDGET_BASE_URL/health` and an authenticated `GET /v1/cards` before writing any code. Then: 1. Identify the surfaces in this project that an iOS widget should reflect (status, build state, queue depth, in-progress jobs, etc.). 2. For each, pick a template (`summary`, `progress`, `list`, `action`, or `chart`) per llms.md's decision matrix. 3. Add the smallest possible publish path — POST one card to `/v1/cards/upsert`, or one related snapshot to `/v1/cards/upsert-batch`, using stable ids. No SDK, no class hierarchy. 4. If something is time-bounded with a clear end (a build, a charge cycle, a delivery), use a Live Activity instead of a card. Constraints: - Use a stable `id` per logical thing — never embed timestamps or run ids. - Never put secrets or PII in card fields. They render on the Lock Screen. - Always end Live Activities. Never make destructive actions auto-run from widgets. - Don't publish more than ~once a minute per card unless the value actually changed. If this project is itself a Cloudflare Worker, see the "Notes for Cloudflare Workers callers" section in llms.md — same-account integrations should use a Service Binding instead of a public HTTPS fetch. ``` ## Anatomy ``` 00widget/ ios/ # SwiftUI app + WidgetKit extension + Live Activity (iOS 26+) server/ # Cloudflare Worker (TypeScript) — REST API + APNs fan-out examples/ # curl scripts showing how any agent can publish state marketing/ # Screenshot and App Preview sources, docs, and entry points artifacts/ # Generated marketing output (ignored by Git) ``` ## Quick start ### 1. Backend ``` cd server npm install install -m 600 .dev.vars.example .dev.vars # fill in SESSION_SECRET; enable the local fallback only when needed npx wrangler dev ``` Then: ``` curl -s http://localhost:8787/health ``` ### 2. Examples ``` cd examples install -m 600 env.example.sh env.sh # edit BASE_URL and API_KEY ./upsert-solar.sh ``` ### 3. iOS Requires macOS with Xcode 26+, iOS 26 simulator or device, and [XcodeGen](https://github.com/yonaskolb/XcodeGen). ``` brew install xcodegen cd ios xcodegen open ZeroZeroWidget.xcodeproj ``` In Xcode, change the bundle id and App Group to values your Apple Developer team owns (see `ios/README.md`), then run. ## Data model See `ios/Sources/Shared/Models/` (Swift) and `server/src/types.ts` (zod) — the two are kept in lockstep. - **DashboardCard** — a single widget tile. Templates: `summary`, `progress`, `list`, `action`, `chart`. - **LiveActivitySession** — a Lock Screen / Dynamic Island activity. - **ActionDefinition** — a button that runs a backend-defined action via `POST /v1/actions/:id/run`. ## Web sign-in and admin `/login` signs a person in with the same Apple ID they use in the iOS app. Signing in establishes identity, not authority: `ADMIN_EMAILS` names the addresses whose sessions additionally carry admin capabilities, and every route under `/admin` asserts that capability rather than assuming it. **Signing in does not sign you up.** The callback resolves the Apple identity against the account the app created and turns away one it does not recognise, so finding this endpoint is not a way to become a tenant. `WEB_SIGNUP_ENABLED` (off by default) opts a deployment into web account creation. The admin dashboard at `/admin` lists cards, devices, push tokens, Live Activities, pending activities, and push-to-start tokens across every tenant. It can also create and revoke tenant credentials and delete tenant data, so access grants full administrative control rather than read-only visibility. An `API_KEYS` bootstrap login (`ADMIN_API_TOKEN_LOGIN=true`, off by default) covers a deployment that has no accounts yet. Create least-privilege tenant API tokens from `/admin` using the tenant owner email and a permission preset; those generated credentials are what apps and agents use for `/v1/*`. Setup walkthrough: `server/README.md` → "Web sign-in". ## Documentation - `ios/README.md` — Xcode setup, entitlements, signing. - `server/README.md` — Worker deploy, D1 binding, APNs secrets, web sign-in and admin. - `examples/README.md` — publishing state from any shell or agent. - `docs/llms.md` — for agents (Claude Code / Codex) integrating *another* project with 00Widget. - `docs/brand/README.md` — logo, colors, tagline rules. - `marketing/screenshots/README.md` — raw capture, promotional composition, and App Store screenshot workflow. - `marketing/app-preview/README.md` — App Store Preview capture, rendering, and validation workflow. ## Status Working end-to-end. Cards publish, Live Activities start/update/end, push-to-start is wired, and APNs payloads are verified against Apple's current docs (date-stamped in `server/src/apns.ts`). **Push-to-start (ActivityKit, iOS 17.2+)** — fully implemented. iOS observes `Activity<ZeroZeroWidgetActivityAttributes>.pushToStartTokenUpdates` from `didFinishLaunchingWithOptions`, registers via `POST /v1/live-activities/register-start-token`. The backend's `POST /v1/live-activities/start` sends the start event to all registered devices and falls back to the pending-queue path if no token is registered (or if the APNs delivery fails). End-to-end verification needs `.p8` credentials configured on the Worker. **tvOS activity dashboard** — the Apple TV app lists ongoing Live Activities above its widgets. The backend exposes one deduplicated tenant-scoped view across pending starts and registered device activities, while tvOS renders countdowns and progress locally. **WidgetKit `pushHandler` (iOS 26+)** — fully implemented. Each widget configuration calls `.pushHandler(ZeroZeroWidgetPushHandler.self)`. The handler persists WidgetKit’s canonical token/configuration snapshot in the App Group, and the host app reconciles it at launch, on foreground, after app-build changes, and through a short bounded retry while WidgetKit finishes generating a token. Backend pushes carry `aps.content-changed: true`, use budget-aware per-tenant cadence, and durably coalesce suppressed changes into one delayed queue delivery when the cadence window opens. A successful foreground app fetch also requests targeted timeline reloads immediately. End-to-end verification still needs `.p8` credentials and a physical device. ## License Source code is MIT licensed. The 00Widget name and brand assets are excluded; see [LICENSE](./LICENSE) and [docs/brand/LICENSE](./docs/brand/LICENSE).