Set up your agent

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

Install #

uploads install finds your agent runtime and adds the agent skills and the hosted MCP server:

uploads install

Using Claude Code or Codex? Install the plugin instead.

Or set up by hand

Add the skills:

npx skills add buildinternet/uploads

Then register the MCP server with your runtime:

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

codex mcp add uploads --url https://agents.uploads.sh/mcp

Add it in Cursor’s MCP settings, or in .cursor/mcp.json:

{
  "mcpServers": {
    "uploads": { "url": "https://agents.uploads.sh/mcp" }
  }
}

opencode mcp add uploads --url https://agents.uploads.sh/mcp

Claude Code & Codex plugins #

The plugin bundles the skills, the MCP server, and the pre-PR reminder. In Claude Code, add the marketplace, then install:

/plugin marketplace add buildinternet/uploads

/plugin install uploads@uploads

Codex loads the same repo as a plugin. After you enable it, open /hooks once and trust the hook if Codex asks.

The reminder hook calls the uploads CLI, so install it and run uploads login once.

Tell the agent to capture as it works #

Add a block like this to your project’s instructions file: AGENTS.md, CLAUDE.md, .cursor/rules, or whatever your runtime reads.

## Screenshots
When a change is visible (UI, layout, styling), capture it as you go.
Don't wait for the PR. After each meaningful visual change:

  uploads put ./shot.png --meta path=/route --state after

On a branch, that stages the file for the PR. After opening the PR, run
`uploads attach --promote` to post everything staged. It's safe to run
even if the GitHub App already posted them.

For how staging works, see Stage before a PR exists.

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

Pre-PR screenshot reminder #

Before gh pr create, the reminder hook nudges the agent if the branch touches UI files and nothing is staged. It never blocks the PR. Turn it off with UPLOADS_HOOK_DISABLE=1.

Claude Code and Codex: included in the plugin.
Grok and Cursor: uploads install adds it when those tools are installed.

Skill vs. MCP #

The skills teach the agent when to capture and which uploads command to run. They need the CLI.

The MCP server gives the agent upload tools directly. There are two:

Server	Use it when	Differences
Local, `uploads mcp`	The agent runs on your machine	Same tools as the CLI, including `attach`.
Hosted, `https://agents.uploads.sh/mcp`	The agent has no local checkout	No `attach` and no git defaults. Pass `repo` and `branch` to `put`, then call `promote` once the PR exists.

To use the local server instead of the hosted one:

claude mcp add uploads -- uploads mcp

codex mcp add uploads -- uploads mcp

Experimental: AI labels #

Experimental and off by default. The uploads.sh team turns it on per workspace. To try it, open an issue on the GitHub repo.

When it’s on, uploads.sh labels each file shortly after it’s uploaded. The labels never replace a path or state you set, and a labeling error never fails the upload. A label it isn’t confident about is left off.

Key	Values
`ai.kind`	`screenshot` `photo` `diagram` `document` `code` `ui` `other`
`ai.surface`	`mobile` `desktop` `tablet` `unknown`
`ai.screen`	`login` `signup` `settings` `profile` `dashboard` `analytics` `list` `detail` `form` `search` `modal` `onboarding` `empty` `error` `checkout` `other`
`ai.tags`	Up to five kebab-case labels (raster images under 512 KiB)
`ai.summary`	One short sentence (raster images under 512 KiB)
`ai.classifier`	The labeler version, currently `v3`

Labels aren’t in the upload’s response. Read them afterward, or search by them:

uploads meta get <key>          # one file's labels
uploads find ai.screen=login    # files with a label

From an MCP client, use get_metadata and find_files. Clients can’t set or delete ai.* keys.