00Widget

00Widget

あらゆるエージェント向けのウィジェット。

再利用可能な Apple プラットフォーム向けコンパニオンアプリと Cloudflare Worker バックエンドです。Claude、ChatGPT、自動化ツール、そして自作ソフトウェアに、ウィジェット、Live Activities、Dynamic Island、Apple TV ダッシュボードを通じたネイティブな出力チャネルを提供します。

サーバーから UI が送信されることはありません。送信されるのは、少数のテンプレートに準拠した構造化状態のみです。Apple アプリは、定義済みの SwiftUI ビューを通じてその状態を表示します。

接続方法を選択

Claude、ChatGPT、その他の MCP ホスト

Model Context Protocol に対応したホストは、統合コードを追加せずに 00Widget にデータを公開できます。カスタムコネクターとして <BASE_URL>/mcp を追加し、サインインしてテナントを選択してください。ツールは REST ルートと同じハンドラーを使用するため、両方のインターフェースの動作に差異が生じることはありません。

MCP はデフォルトで無効です（wrangler.toml の MCP_ENABLED）。これは、パブリックインターネット上で API トークンを発行するブラウザーフローを公開するためです。コネクターを承認するにはサインインが必要で、発行される認証情報は承認者自身のアカウントに限定された通常のテナントトークンです。/admin から取り消すことができます。

詳細：server/README.md →「MCP」。

既存のコネクターに触れずに、追加の MCP Apps UI をテストできます。同じ Worker を MCP_PREVIEW_ENABLED = "true" でデプロイし、Developer Mode の別の接続として <BASE_URL>/mcp-preview を追加してください。バージョン管理された HTML リソースを基盤として、読み取り専用の render_card、render_activity、render_dashboard ツールが追加されます。/mcp の既存の検出機能とツールの契約はそのまま維持されます。

アプリ、スクリプト、自動化ツール、コーディングエージェント

別のリポジトリ（CI パイプラインやホームオートメーションのスクリプトなど）で作業していて、Claude Code / Codex に 00Widget インスタンスへの状態公開をさせたい場合は、次の内容をエージェントに貼り付けてください。これだけで完結します。

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`, `chart`, `history`, `breakdown`, `briefing`, or `timeline`) 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.

構成

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)

クイックスタート

1. バックエンド

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

続いて：

curl -s http://localhost:8787/health

2. サンプル

cd examples
install -m 600 env.example.sh env.sh   # edit BASE_URL and API_KEY
./upsert-solar.sh

3. iOS

macOS、Xcode 26 以降、iOS 26 のシミュレーターまたはデバイス、および XcodeGen が必要です。

brew install xcodegen
cd ios
xcodegen
open ZeroZeroWidget.xcodeproj

Xcode で、バンドル ID と App Group を、Apple Developer チームが所有する値に変更してから実行してください（ios/README.md を参照）。

データモデル

ios/Sources/Shared/Models/（Swift）および server/src/types.ts（zod）を参照してください。両者は常に同期されています。

• DashboardCard — 1 つのウィジェットタイルです。テンプレート：summary、progress、list、action、chart、history、breakdown、briefing、timeline。
• LiveActivitySession — ロック画面 / Dynamic Island のアクティビティです。
• ActionDefinition — POST /v1/actions/:id/run を介して、バックエンドで定義されたアクションを実行するボタンです。

Web サインインと管理

/login では、iOS アプリで使用するものと同じ Apple ID でサインインします。 サインインによって確立されるのは本人確認であり、権限ではありません。ADMIN_EMAILS には、セッションに管理者権限も付与するメールアドレスを指定します。また、/admin 配下のすべてのルートでは、権限があることを確認し、権限があるものとみなして処理することはありません。

サインインしても、アカウント登録はされません。 コールバックは、Apple ID をアプリが作成したアカウントと照合し、認識できない場合はアクセスを拒否します。そのため、このエンドポイントを見つけてもテナントになることはできません。WEB_SIGNUP_ENABLED（デフォルトでは無効）を有効にすると、デプロイ環境での Web アカウント作成が可能になります。

/admin の管理ダッシュボードでは、すべてのテナントのカード、デバイス、プッシュトークン、Live Activity、保留中のアクティビティ、プッシュ開始トークンを一覧表示します。また、テナントの認証情報の作成と失効、テナントデータの削除も行えるため、アクセス権を付与すると読み取り専用ではなく、完全な管理権限が与えられます。API_KEYS による初期ログイン（ADMIN_API_TOKEN_LOGIN=true、デフォルトでは無効）は、アカウントがまだないデプロイ環境で利用できます。

管理機能はデフォルトで有効です。server/wrangler.toml の [vars] にある ADMIN_ENABLED = "false" を設定して再デプロイすると、セッションやデータベースへのアクセス前に、/admin とすべての変更用エンドポイントが 404 を返すようになります。Web サインイン、アカウントダッシュボード、MCP 認可、公開 API は引き続き利用できます。

/admin から、テナントオーナーのメールアドレスと権限プリセットを指定して、最小権限のテナント API トークンを作成してください。生成された認証情報は、アプリやエージェントが /v1/* にアクセスする際に使用します。

セットアップ手順：server/README.md → 「Web サインイン」。

ドキュメント

• ios/README.md — Xcode のセットアップ、エンタイトルメント、署名。
• server/README.md — Worker のデプロイ、D1 バインディング、APNs シークレット、Web サインインと管理。
• examples/README.md — 任意のシェルやエージェントから状態を公開する方法。
• docs/llms.md — 00Widget と連携する別のプロジェクトを統合するエージェント（Claude Code / Codex）向け。
• docs/brand/README.md — ロゴ、カラー、タグラインのルール。
• marketing/screenshots/README.md — 画像の未加工キャプチャ、プロモーション用の構成、App Store スクリーンショットのワークフロー。
• marketing/app-preview/README.md — App Store Preview のキャプチャ、レンダリング、検証のワークフロー。

ステータス

エンドツーエンドで動作します。カードの公開、Live Activity の開始／更新／終了、プッシュ開始の接続は実装済みで、APNs ペイロードは Apple の最新ドキュメント（server/src/apns.ts に日付を記録）に照らして検証済みです。

プッシュ開始（ActivityKit、iOS 17.2 以降） — 完全に実装済みです。iOS は didFinishLaunchingWithOptions から Activity<ZeroZeroWidgetActivityAttributes>.pushToStartTokenUpdates を監視し、POST /v1/live-activities/register-start-token を使って登録します。バックエンドの POST /v1/live-activities/start は、登録済みのすべてのデバイスに開始イベントを送信します。トークンが登録されていない場合、または APNs 配信に失敗した場合は、保留キューの経路にフォールバックします。エンドツーエンドの検証には、Worker に .p8 認証情報を設定する必要があります。

tvOS アクティビティダッシュボード — Apple TV アプリでは、ウィジェットの上に進行中の Live Activity が表示されます。バックエンドは、保留中の開始と登録済みデバイスのアクティビティを重複排除した、テナント単位のビューを提供します。tvOS はカウントダウンと進捗をローカルで表示します。

WidgetKit pushHandler（iOS 26 以降） — 完全に実装済みです。各ウィジェット設定で .pushHandler(ZeroZeroWidgetPushHandler.self) を呼び出します。ハンドラーは WidgetKit の正規トークン／設定スナップショットを App Group に保存し、ホストアプリは起動時、フォアグラウンド復帰時、アプリのビルド変更後、および WidgetKit がトークンを生成する間の短時間の上限付き再試行を通じて、それを照合します。バックエンドからのプッシュには aps.content-changed: true が含まれ、テナントごとの頻度制限を考慮した頻度で送信されます。また、抑制された変更は、頻度制限のウィンドウが開いた際にキューから遅延配信できるよう、永続的にまとめられます。フォアグラウンドでのアプリ取得が成功すると、対象を絞ったタイムラインの再読み込みも即座に要求します。エンドツーエンドの検証には、.p8 認証情報と実機が必要です。

ライセンス

ソースコードは MIT ライセンスです。00Widget の名称およびブランドアセットは対象外です。 LICENSE および docs/brand/LICENSE をご覧ください。