Set up your agent

Teach a coding agent to upload and attach media on its own.

Install #

One command detects your agent runtime and installs everything it needs: the agent skills (attach workflow, CLI reference, and screenshot annotations) plus the hosted MCP server.

uploads install

Using Claude Code or Codex? Install everything as one plugin instead, with the pre-PR hook and a slash command included — see Claude Code & Codex plugins →.

Or set up by hand

Add the skills with npx skills, then register the MCP server with your runtime's own MCP registration — shown here for Claude Code:

npx skills add buildinternet/uploads

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

Claude Code & Codex plugins #

Install the agent skills, the MCP server, an /uploads:attach command, and a pre-PR screenshot reminder hook as one plugin, from the uploads marketplace. Add the marketplace, then install:

/plugin marketplace add buildinternet/uploads

/plugin install uploads@uploads

Codex uses the same repo as a plugin (.codex-plugin/plugin.json) — the same skills, MCP server, and hook. After enabling it, open /hooks once and trust the hook if Codex asks. Both plugins run uploads hook pre-pr-screenshot, so keep theuploads CLI on your PATH and run uploads login once.

Skill vs. MCP #

The skill teaches the agent when and how to use the CLI — for example staging a before/after with uploads put, or baking callouts onto a capture with uploads screenshot --annotate.

The local stdio MCP (uploads mcp) exposes the same tools as the CLI, includingattach. Register it with any MCP client, e.g.:

claude mcp add uploads -- uploads mcp

The hosted MCP at agents.uploads.sh is for agents with no local checkout. It hasput, list, delete, and more, but not attach, and no git defaults — pass repo and branch to put to stage, then repo, pr, and branch to promote once a PR exists. Hosted put/comment honor a repo's .uploads.yml the same way the bot does.

Want the guided version? The agent walkthrough takes a coding agent from install to a first staged before/after.

Stage screenshots as the agent works #

Any agent that can run a shell command can capture at each visual milestone and stage it — no PR required yet, and no --branch flag needed on a branch:

uploads put ./shot.png --state before # or --state after

A bare uploads screenshot stages the same way, carrying its derived path, url, env, and viewport metadata through promotion. Keep using --state — it's the one thing no tool can infer from the image.

Once a PR opens, the comment assembles itself: via the GitHub App webhook, or the next uploads attach (or uploads attach --promote) without the App. See the stage-as-you-go walkthrough for the full loop.

Put it in your instructions file #

Add a block like this to your project's instructions file — AGENTS.md, CLAUDE.md, .cursor/rules, wherever your runtime reads project instructions:

## Screenshots
When a change is visually observable (UI, layout, styling), capture it as you
go — don't wait until the PR is open. After each meaningful visual change:

  uploads put ./shot.png --state before   # or --state after

On a branch, that stages automatically — no --branch flag needed. Stage
before/after pairs where it makes sense. No need to open the PR first —
staged files are promoted into the PR's attachments comment automatically.

Requires the uploads CLI on PATH and uploads login already run once — see Install above.

Pre-PR screenshot reminder #

Before gh pr create, agents can get a non-blocking nudge when the branch touches UI files and nothing is staged on uploads.sh. The handler isuploads hook pre-pr-screenshot — fail-open, never blocks the PR. Disable with UPLOADS_HOOK_DISABLE=1.

Claude Code and Codex — bundled in theplugin (Codex: trust once via /hooks).
Grok and Cursor —uploads install hooks writes a user-global manifest when those tools are present (included in plain uploads install).

No reminder is required — uploads attach --promote (no file arguments) right after opening a PR picks up everything staged against the branch and posts or refreshes the attachments comment; it exits 0 even if nothing was staged.