{ "markdown": "
\n\n\"uploads.sh\n\n

uploads

\n\n**The missing upload command for coding agents.**\n\nCapture screenshots as you work. When the pull request opens, uploads.sh puts\nthem in one tidy comment that updates automatically on each revision. Hosted\nuploads.sh is free to start. Connect your own bucket — Cloudflare R2 or any\nS3-compatible provider — so storage in that bucket is unmetered, or self-host\nthe open-source service.\n\n

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

\n\n

\n \"skills.sh\"\n \"CI\"\n \"npm\n \"MCP\n \"GitHub\n \"Ask\n \"License:\n

\n\n

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

\n\n
\n\n---\n\n## Screenshots ready when the pull request opens\n\n**uploads** hosts screenshots and other files at stable URLs that coding agents\ncan use in pull requests and issues. On a branch, `uploads put` stages each file\nas soon as it is ready. When the pull request opens, uploads.sh promotes the\nstaged files into one managed comment.\n\nGitHub's own attachments work from a browser and, since GitHub CLI 2.99\n(September 2026), from `gh … --attach`, but only once a pull request or issue\nexists, and the files stay private to GitHub. uploads.sh gives agents a stable\npublic URL from the same terminal where they build and test the change, while\nthe branch is still in progress. The hosted MCP server does the same for agents\nthat cannot run a command at all, taking files as bytes or a URL. GitHub has no\npublic API (yet) for that.\n\nKeys are hash-free, so re-uploading the same filename overwrites in place and\nthe URL never changes — every embed of it updates at once. Workspaces keep\ntenants (and their budgets and key policies) apart.\n\nThis repo is the source of the canonical deployment at\n[uploads.sh](https://uploads.sh): the API worker, auth worker, MCP server, the\nAstro web app, and the `@buildinternet/uploads` CLI (published to npm from\n[`packages/uploads`](packages/uploads)).\n\n## What it looks like\n\nOne comment per PR, rewritten in place on every sync. Files tagged\n`--state before` and `--state after` pair into a side-by-side table; anything\nelse lands below it.\n\n
\n \"The\n
\n\nThe real comment on\n[#436](https://github.com/buildinternet/uploads/pull/436#issuecomment-5052307515).\n\nPairing is by `--meta path=…` when several pairs share a comment (one `before`\nand one `after` per path), and falls back to filenames that differ only by a\n`before`/`after` token — `hero-before.webp` with `hero-after.webp`.\n\nEverything you attach also lands in your workspace, grouped by where it came\nfrom — pages by `path`, projects by `repo` or `app` — and browsable from one\nplace.\n\n
\n \"The\n
\n\nThe screenshots view groups uploads by project and path.\n\nOpen any file for a share page: copy-ready embeds (Markdown, HTML, and more),\nthe raw URL, and a delete button.\n\n
\n \"A\n
\n\nEach file's share page — copy-ready embeds, details, and delete.\n\n## Quick start\n\nInstall the CLI and sign in once:\n\n```bash\nnpm install --global @buildinternet/uploads\nuploads login\n```\n\nUpload a file and tag the page it shows:\n\n```bash\nuploads put ./settings.png --meta path=/settings\n```\n\nOn a branch, `put` stages the file automatically. Open the pull request however\nyou normally would. The [GitHub App](https://uploads.sh/docs/github-app)\npromotes the staged files into one managed attachments comment.\n\n## More ways to upload\n\nUse the same commands for before-and-after evidence, an open pull request, a\nbrowser capture, or an annotated image:\n\n```bash\n# Pair two states from the same page in the pull request comment.\nuploads put ./before.png --meta path=/settings --state before\nuploads put ./after.png --meta path=/settings --state after\n\n# See what this branch will attach when the pull request opens.\nuploads staged\n\n# Attach files directly when a pull request or issue is already open.\nuploads attach ./before.png ./after.png\n\n# Capture, annotate, and upload a page in one command.\nuploads screenshot http://localhost:4321/settings --via local --annotate ./callouts.json\n```\n\n`attach` detects the repository and current PR through `gh`, uploads all files,\nand creates or updates that same one comment. Without the GitHub App, run\n`uploads attach --promote` after opening the pull request to promote files that\nyou staged earlier. All commands run under `npx @buildinternet/uploads …`\nwithout a global install.\n\nSign in with GitHub or a magic link, then create your own workspace or accept\nan invite into one — see [enrollment](docs/enrollment.md). Hosted files are\npublic URLs — private-repo attachments get non-guessable links\n([how that works](docs/private-attachments.md)), but anyone holding a URL can\nview the file. Do not upload secrets or sensitive UI.\n\n## Connect your agent\n\nThe hosted MCP server runs at `https://agents.uploads.sh/mcp` and is listed in the\n[MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers?search=sh.uploads/mcp)\nas `sh.uploads/mcp`. Local stdio is `uploads mcp` on the same npm package.\n\n```bash\n# Claude Code\nclaude mcp add --transport http uploads https://agents.uploads.sh/mcp\n\n# Codex\ncodex mcp add uploads --url https://agents.uploads.sh/mcp\n\n# OpenCode\nopencode mcp add uploads --url https://agents.uploads.sh/mcp\n```\n\n`uploads install` adds the agent skills and the MCP server, so future sessions\ncan capture each visual milestone without being asked. The skills also install\nstandalone into any agent runtime:\n\n```bash\nnpx skills add buildinternet/uploads\n```\n\nThat installs three skills: `github-screenshots` (visuals → PRs/issues),\n`uploads-cli` (full CLI reference), and `annotate-screenshots` (callouts and\nredaction on a capture).\n\nFull CLI usage, including annotations, managed comments, and public galleries,\nlives in [docs/cli.md](docs/cli.md).\nREST routes are in [docs/api.md](docs/api.md).\n\n## What's in this repo\n\n| Path | What |\n| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `apps/` | The deployables: the REST API worker (`api.uploads.sh`), the auth worker, the remote MCP server, and the Astro site at uploads.sh |\n| `packages/` | Shared code — most notably `@buildinternet/uploads` (the CLI, published to npm) and `@uploads/storage` (the files-sdk adapter factory all storage goes through) |\n| `skills/` | The three agent skills that ship to users |\n| `hooks/`, `plugins/`, `.mcp.json` | Agent-runtime wiring: the shared pre-PR screenshot hook and the Claude / Codex plugin manifests |\n| `server.json` | MCP Registry listing (`sh.uploads/mcp`): stdio `uploads mcp` plus the hosted remote |\n\nEach worker and the web app deploy separately. All storage access goes through\n`createStorage()` in `packages/storage` — adding a provider is one new case\nplus peer deps, no API changes.\n\n## Docs\n\nProduct docs — install, the staged loop, the GitHub App, limits — live at\nhttps://uploads.sh/docs. The docs in this repo are the companion: CLI and API\nreference, contributor setup, and operator material, all mapped from\n[docs/README.md](docs/README.md).\n\nHow to set up, test, and open a pull request: [CONTRIBUTING.md](CONTRIBUTING.md).\nWhere the project is headed: [VISION.md](VISION.md). Agent working conventions\nlive in [AGENTS.md](AGENTS.md), and agents that land on this repo should start\nat [llms.txt](llms.txt). The product site serves https://uploads.sh/llms.txt\nand https://uploads.sh/llms-full.txt.\n\n## Local development\n\n**Prerequisites:** Node ≥24 and pnpm ≥11 (`corepack enable`). No Cloudflare\naccount needed for the core local loop — `wrangler dev` simulates R2, KV, and\nD1 on disk:\n\n```bash\npnpm bootstrap # one-command setup: tooling, deps, env vars, local D1, default workspace\npnpm dev # API on :8787 (local R2 + KV + D1)\n```\n\n`bootstrap` is idempotent, and `pnpm doctor` diagnoses a setup without changing\nit. The rest of the loop — the authenticated dev stack, the check and test\ngates, and how to open a pull request — is in\n[CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License\n\n[Apache 2.0](LICENSE).\n", "bytes": 11010, "sha": "ef1470af259ca6b56b69aa89db14ea9c642e1239104f1023b266a51feeb181bc", "repo_slug": "buildinternet/uploads", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_sh_uploads_mcp_80190d8f/readme" }