Set up your agent

Claude Code & Codex plugins #

Install the agent skills, the MCP server, 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 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 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, including attach and put with contentUrl. Register it with either client:

# Claude Code
claude mcp add uploads -- uploads mcp

# Codex
codex mcp add uploads -- uploads mcp

The hosted MCP at https://agents.uploads.sh/mcp is for agents with no local checkout. It has put, 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 takes contentBase64 or contentUrl (a public HTTPS file the worker fetches; the filename comes from the URL path when you omit it). Hosted put/comment honor a repo’s .uploads.yml the same way the bot does.

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 is uploads hook pre-pr-screenshot — fail-open, never blocks the PR. Disable with UPLOADS_HOOK_DISABLE=1.

• Claude Code and Codex — bundled in the plugin (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.