Set up your agent

Claude Code plugin #

On Claude Code you can install everything as one plugin — both agent skills, an MCP server, and an /uploads:attach command — from the uploads marketplace. Add the marketplace, then install:

The bundled MCP server runs the local uploads mcp over stdio and reads the token uploads login already stored, so once you've signed in there's nothing else to wire up — just make sure the uploads CLI is on your PATH.

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.:

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. --stateis 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.

Optional: remind before the PR opens #

A useful backstop is a check at gh pr create time: is anything staged for this branch? If your runtime supports pre-command hooks — or you wrap gh pr create yourself — it's a few lines of shell. Keep it fail-open — a broken check should never block a PR from being created.

#!/bin/sh
# Run before `gh pr create` (wrapper, or your agent's pre-command hook).
# Fails open: any error here just skips the reminder, never blocks the PR.
set -u
# --format json always prints a valid document, even with zero files staged —
# no empty-stdout special case to handle here.
staged=$(uploads staged --format json 2>/dev/null) || exit 0
case "$staged" in
  *'"files": []'*)
    echo "note: nothing staged for this branch — if this PR touches UI," >&2
    echo "consider 'uploads put ./shot.png' first" >&2
    ;;
esac
exit 0

The Claude Code plugin ships this reminder as a bundled hook. And no reminder is required at all — 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.