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.

Using claude.ai or Cowork? Add uploads from the Claude directory 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, the pre-PR reminder, and, in Claude Code, mods. 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. When files are staged, it says whether they attach on their own when the PR opens. 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.

Claude Code mods #

In Claude Code, the plugin also ships mods: code that runs inside Claude Code and can add to its interface. The plugin includes:

Staged media band: shows the files staged for your branch above the prompt, and attaches them when gh pr create opens the PR.

Mods use the local uploads CLI, so install it and run uploads login once. Change their options, such as the automatic attach, in /plugin. Mods need Claude Code 2.1.287 or later. Older versions, Codex, and hosted MCP setups get the rest of the plugin.

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.