uploads

The missing upload command for coding agents.

Capture screenshots as you work. When the pull request opens, uploads.sh puts them in one tidy comment that updates automatically on each revision. Hosted uploads.sh is free to start. Connect your own bucket — Cloudflare R2 or any S3-compatible provider — so storage in that bucket is unmetered, or self-host the open-source service.

uploads.sh  ·  Docs  ·  npm →  ·  Quick start  ·  What it looks like  ·  What's in this repo  ·  Develop

_{Under active development. uploads.sh is being built in the open, so APIs can still change. Feedback is welcome — open an issue.}

Screenshots ready when the pull request opens

uploads hosts screenshots and other files at stable URLs that coding agents can use in pull requests and issues. On a branch, uploads put stages each file as soon as it is ready. When the pull request opens, uploads.sh promotes the staged files into one managed comment.

GitHub's own attachments work from a browser and, since GitHub CLI 2.99 (September 2026), from gh … --attach, but only once a pull request or issue exists, and the files stay private to GitHub. uploads.sh gives agents a stable public URL from the same terminal where they build and test the change, while the branch is still in progress. The hosted MCP server does the same for agents that cannot run a command at all, taking files as bytes or a URL. GitHub has no public API (yet) for that.

Keys are hash-free, so re-uploading the same filename overwrites in place and the URL never changes — every embed of it updates at once. Workspaces keep tenants (and their budgets and key policies) apart.

This repo is the source of the canonical deployment at uploads.sh: the API worker, auth worker, MCP server, the Astro web app, and the @buildinternet/uploads CLI (published to npm from packages/uploads).

What it looks like

One comment per PR, rewritten in place on every sync. Files tagged --state before and --state after pair into a side-by-side table; anything else lands below it.

_{The real comment on #436.}

Pairing is by --meta path=… when several pairs share a comment (one before and one after per path), and falls back to filenames that differ only by a before/after token — hero-before.webp with hero-after.webp.

Everything you attach also lands in your workspace, grouped by where it came from — pages by path, projects by repo or app — and browsable from one place.

_{The screenshots view groups uploads by project and path.}

Open any file for a share page: copy-ready embeds (Markdown, HTML, and more), the raw URL, and a delete button.

_{Each file's share page — copy-ready embeds, details, and delete.}

Quick start

Install the CLI and sign in once:

npm install --global @buildinternet/uploads
uploads login

Upload a file and tag the page it shows:

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

On a branch, put stages the file automatically. Open the pull request however you normally would. The GitHub App promotes the staged files into one managed attachments comment.

More ways to upload

Use the same commands for before-and-after evidence, an open pull request, a browser capture, or an annotated image:

# 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 detects the repository and current PR through gh, uploads all files, and creates or updates that same one comment. Without the GitHub App, run uploads attach --promote after opening the pull request to promote files that you staged earlier. All commands run under npx @buildinternet/uploads … without a global install.

Sign in with GitHub or a magic link, then create your own workspace or accept an invite into one — see enrollment. Hosted files are public URLs — private-repo attachments get non-guessable links (how that works), but anyone holding a URL can view the file. Do not upload secrets or sensitive UI.

Connect your agent

The hosted MCP server runs at https://agents.uploads.sh/mcp and is listed in the MCP Registry as sh.uploads/mcp. Local stdio is uploads mcp on the same npm package.

# 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 adds the agent skills and the MCP server, so future sessions can capture each visual milestone without being asked. The skills also install standalone into any agent runtime:

npx skills add buildinternet/uploads

That installs three skills: github-screenshots (visuals → PRs/issues), uploads-cli (full CLI reference), and annotate-screenshots (callouts and redaction on a capture).

Full CLI usage, including annotations, managed comments, and public galleries, lives in docs/cli.md. REST routes are in docs/api.md.

What's in this repo

Each worker and the web app deploy separately. All storage access goes through createStorage() in packages/storage — adding a provider is one new case plus peer deps, no API changes.

Docs