uploads.sh

---

プルリクエストが作成された時点で成果物を準備完了

uploads は、コーディングエージェントが生成する成果物を、プルリクエストや Issue で利用できる安定した公開 URL でホストします。スクリーンショットや画面録画だけでなく、テストレポート、ログ、JSON、CSV、Markdown、PDF、ZIP アーカイブにも対応しています（全リストはプランと制限をご覧ください）。ブランチ上で uploads put を実行すると、ファイルの準備ができ次第、それぞれをステージングします。プルリクエストが作成されると、uploads.sh がステージング済みのファイルをひとつの管理対象コメントにまとめます。

GitHub の添付ファイル機能はブラウザーから利用でき、GitHub CLI 2.99（2026 年 9 月）以降は gh … --attach でも利用できます。ただし、プルリクエストまたは Issue が存在してからでなければ使えず、ファイルは GitHub 独自のホスティング上にとどまるため、ほかの場所に埋め込んだり取得したりできません。uploads.sh を使えば、変更をビルドしてテストするターミナルから、ブランチでの作業中にエージェントへ安定した公開 URL を提供できます。GitHub には（まだ）そのための公開 API がありません。ホスト型 MCP サーバーは、コマンドを一切実行できないエージェントに対しても同じことを行い、ファイルをバイト列または URL として受け取ります。

キーにハッシュが含まれないため、同じファイル名を再アップロードすると同じ場所で上書きされ、URL は変わりません。その URL を使ったすべての埋め込みが一度に更新されます。ワークスペースによって、テナント（およびその予算とキーのポリシー）は分離されます。

このリポジトリには、uploads.sh の正式なデプロイに使われるソースコードが含まれています。API ワーカー、認証ワーカー、MCP サーバー、Astro ウェブアプリ、および packages/uploads から npm に公開される @buildinternet/uploads CLI です。

表示例

PR ごとにコメントを 1 つ作成し、同期のたびにその場で書き換えます。 --state before と --state after のタグが付いたファイルはペアになって横並びの表に表示され、それ以外の画像や動画はその下に表示されます。メディア以外のファイル（レポート、ログ、アーカイブ）は、種類とサイズを記載したファイルの表に表示されます。

_{#436 にある実際のコメントです。}

1 つのコメントに複数のペアがある場合は、--meta path=… によってペアを組みます（各パスに before と after が 1 つずつ）。それがない場合は、before／after のトークンだけが異なるファイル名を使います。たとえば、hero-before.webp と hero-after.webp のように組み合わせます。

添付したファイルはすべてワークスペースにも保存され、元の場所（ページは path、プロジェクトは repo または app）ごとにまとめられ、1 か所から閲覧できます。

_{スクリーンショットビューでは、アップロードがプロジェクトとパスごとにまとめられます。}

ファイルを開くと共有ページが表示されます。コピーしてすぐ使える埋め込みコード（Markdown、HTML など）、直接 URL、削除ボタンが用意されています。

_{各ファイルの共有ページには、コピーしてすぐ使える埋め込みコード、詳細、削除操作があります。}

クイックスタート

CLI をインストールして、一度サインインします。

npm install --global @buildinternet/uploads
uploads login

ファイルをアップロードし、そのファイルが表示されるページをタグ付けします。

uploads put ./settings.png --meta path=/settings

ブランチ上では、put によりファイルが自動的にステージングされます。あとは通常どおりプルリクエストを作成してください。GitHub App が、ステージング済みのファイルを 1 つの管理された添付ファイルコメントにまとめます。

その他のアップロード方法

変更前と変更後の比較資料、オープン中のプルリクエスト、ブラウザーのキャプチャ、注釈付き画像にも同じコマンドを使えます。

# Pair two states from the same page in the pull request comment.
uploads put ./before.png --meta path=/settings --state before
uploads put ./after.png --meta path=/settings --state after

# See what this branch will attach when the pull request opens.
uploads staged

# Attach files directly when a pull request or issue is already open.
uploads attach ./before.png ./after.png

# Capture, annotate, and upload a page in one command.
uploads screenshot http://localhost:4321/settings --via local --annotate ./callouts.json

attach は gh を通じてリポジトリと現在の PR を検出し、すべてのファイルをアップロードして、同じコメントを作成または更新します。GitHub App を使わない場合は、プルリクエストを開いた後に uploads attach --promote を実行すると、以前にステージングしたファイルを公開できます。グローバルインストールは不要で、すべてのコマンドを npx @buildinternet/uploads … 経由で実行できます。

GitHub またはマジックリンクでサインインし、自分のワークスペースを作成するか、招待を受けて参加します。詳しくは登録をご覧ください。ホストされたファイルは公開 URL でアクセスできます。プライベートリポジトリの添付ファイルには推測されにくいリンクが使われます（仕組み）。ただし、URL を知っている人は誰でもファイルを閲覧できます。認証情報、ID、カード番号が写っているように見えるファイルは、公開前に確認のため保留されますが、これに頼らないでください。秘密情報や機密性の高い UI はアップロードしないでください。

CI でスクリーンショットを必須にする

GitHub App は、UI ファイルを変更するプルリクエストに uploads.sh チェックを追加します。テストやビルドと並んで実行され、ワークフローや Actions のステップは必要ありません。初期設定ではレポートのみを行うため、誰もブロックされません。ワークスペースの Settings → GitHub で Require screenshots on UI changes を有効にするか、.uploads.yml で特定のリポジトリに設定すると、スクリーンショットが届くまでチェックが失敗します。

comment:
  check:
    require: [before-after, desktop, mobile] # or just [uploads]

PR のコメントにはチェックリストが表示され、ファイルが届くと自動でチェックが付きます。GitHub の PR にドラッグして追加した画像も対象になるため、uploads.sh を使わないコントリビューターが行き詰まることはありません。また、スクリーンショットが不要な PR は skip-uploads ラベルでスキップできます。マージをブロックするには、ブランチ保護で uploads.sh を必須のステータスチェックに追加してください。セットアップ方法、UI として扱われるファイル、スキップラベルについては、プルリクエストでスクリーンショットを必須にするをご覧ください。

エージェントを接続する

ホスト型 MCP サーバーは https://agents.uploads.sh/mcp で実行されており、 MCP Registry に sh.uploads/mcp として登録されています。ローカルの stdio は同じ npm パッケージの uploads mcp です。

# Claude Code
claude mcp add --transport http uploads https://agents.uploads.sh/mcp

# Codex
codex mcp add uploads --url https://agents.uploads.sh/mcp

# OpenCode
opencode mcp add uploads --url https://agents.uploads.sh/mcp

uploads install を実行すると、エージェントスキルと MCP サーバーが追加されます。これにより、今後のセッションでは、依頼しなくても視覚的な各マイルストーンを記録できます。スキルは、あらゆるエージェントランタイムに単独でインストールすることもできます。

npx skills add buildinternet/uploads

これにより、3 つのスキルがインストールされます。github-screenshots（ビジュアル → PR／issue）、uploads-cli（CLI の全リファレンス）、annotate-screenshots（キャプチャへの吹き出しと墨消し）です。

Claude Code または Codex では、プラグインにスキル、MCP サーバー、PR 作成前のスクリーンショットのリマインダーが含まれています。Claude Code では、ステージされたスクリーンショットがプロンプトの上に表示され、PR が作成されると添付されます。claude.ai と Cowork では、Claude ディレクトリから uploads を追加してください。同じフォルダー（plugins/claude/uploads）が共通のエージェントプラグイン構成であり、xAI plugin marketplaceに uploads として申請されています。

注釈、管理対象コメント、公開ギャラリー、変更フィード（リポジトリ全体または単一のプルリクエスト）を含む CLI の詳細な使い方は、 docs/cli.mdを参照してください。

uploads feed create は、リポジトリ内のスクリーンショットを一覧表示するライブページを出力します。

_{uploads feed create --repo buildinternet/uploads。}

REST エンドポイントについてはdocs/api.mdを参照してください。

このリポジトリの内容

パス	内容
apps/	デプロイ可能なもの：REST API ワーカー（api.uploads.sh）、オプションの公開ビューアー、認証ワーカー、リモート MCP サーバー、Slack アプリ（リンクプレビューと保留中アップロードのメッセージ）、および uploads.sh の Astro サイト
packages/	共有コード — 特に、@buildinternet/uploads（npm に公開されている CLI）、@uploads/storage（すべてのストレージが経由する files-sdk アダプターファクトリー）、@uploads/plugin（Claude／Codex プラグイン版、非公開）
skills/	ユーザーに提供される 3 つのエージェントスキル
hooks/、plugins/、.mcp.json	エージェントランタイムの構成：共有の PR 作成前スクリーンショットフックと Claude／Codex プラグインマニフェスト
server.json	MCP Registry の登録情報（sh.uploads/mcp）：stdio の uploads mcp とホスト型リモートサーバー

各ワーカーと Web アプリは個別にデプロイされます。ストレージへのアクセスはすべて packages/storage の createStorage() を経由します。プロバイダーを追加するには、新しい分岐を 1 つ追加してピア依存関係を設定するだけで、API の変更は不要です。

ドキュメント

製品ドキュメント（インストール、段階的なループ、GitHub App、制限）は https://uploads.sh/docs にあります。このリポジトリのドキュメントは、CLI と API のリファレンス、コントリビューター向けセットアップ、運用者向け資料をまとめた補足資料で、すべて docs/README.md から案内されています。

セットアップ、テスト、プルリクエストの作成方法については、CONTRIBUTING.md をご覧ください。 プロジェクトの今後の方針については、VISION.md をご覧ください。エージェントの作業規約は AGENTS.md に記載されています。このリポジトリにたどり着いたエージェントは、まず llms.txt を確認してください。製品サイトでは https://uploads.sh/llms.txt と https://uploads.sh/llms-full.txt を提供しています。

ローカル開発

前提条件： Node ≥24 と pnpm ≥11（corepack enable）。基本的なローカルループに Cloudflare アカウントは必要ありません。wrangler dev がディスク上で R2、KV、D1 をシミュレートします。

pnpm bootstrap        # one-command setup: tooling, deps, env vars, local D1, default workspace
pnpm dev              # API on :8787 (local R2 + KV + D1)

bootstrap は冪等で、pnpm doctor はセットアップを変更せずに診断します。認証済みの開発スタック、チェックとテストの ゲート、プルリクエストの作成方法など、その他のループについては CONTRIBUTING.md をご覧ください。

ライセンス

Apache 2.0。