Set up your agent

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

One command #

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

uploads install

Or set up each piece yourself — the skills via npx skills, the MCP server with your runtime's 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 #

On Claude Code you can install everything as one plugin — the agent skills (attach workflow, CLI reference, annotations), an MCP server, an /uploads:attach command, and a pre-PR screenshot reminder hook — 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): skills plus the same pre-PR hook. After enabling it, open /hooks once and trust the hook if Codex asks. Both plugins runuploads hook pre-pr-screenshot, so keep the uploads CLI on your PATH and run uploads login once.

Skill vs. MCP #

The skills teach the agent when and how to use the CLI — for example attaching before/after screenshots to the PR it just opened, or baking callouts onto a capture with uploads screenshot --annotate. The MCP server gives agents the same tools (put, attach, list, delete, and more) over HTTP, using the same token as the CLI. Hosted put/comment honor a repo's .uploads.yml the same way the bot does. There's also a local stdio variant — register uploads mcp with any MCP client, e.g.:

claude mcp add uploads -- uploads mcp

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

Stage screenshots as the agent works #

Any agent that can run a shell command can capture at each visual milestone and run a bare uploads put ./shot.png --state before|after — on a branch it stages automatically (issue #403), no --branch flag required. A bare uploads screenshot stages the same way, carrying its derived path/url/env/viewport metadata through promotion.--state is still worth keeping as a habit; it's the one thing no tool can infer from the image. Let the PR comment assemble itself once a PR opens — 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 One command 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.