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 both the agent skill and the hosted MCP server:

uploads install

Or set up each piece yourself — the skill via npx skills, the MCP server with your runtime's MCP registration (shown here for Claude Code):

npx skills add buildinternet/uploads --skill uploads-cli

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 — both agent skills, 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 skill teaches the agent when and how to use the CLI, for example attaching before/after screenshots to the PR it just opened. The MCP server gives agents the same tools (put, attach, list, delete, and more) over HTTP, using the same token as the CLI. 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.