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 installIt lists what it will set up and asks first, installs the skills only for the agents it finds, and prints where they went.
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/uploadsThen register the MCP server with your runtime:
claude mcp add --transport http uploads https://agents.uploads.sh/mcpcodex mcp add uploads --url https://agents.uploads.sh/mcpAdd 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/mcpClaude 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@uploadsCodex 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.
## ScreenshotsWhen 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
For a mobile or desktop app screen with no route, name the screen instead:
uploads put ./shot.png --app ios --screen "Chat" --state after
Add `--caption "<what it shows>"` when a shot needs a word of explanation.
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 runeven 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. If those files are older than 30 days, or they belong to a different branch, it suggests
uploads unstage --branch <name> instead. It never blocks the PR. Turn it off with
UPLOADS_HOOK_DISABLE=1. To check for screenshots on the PR itself, and block merges without them,
see Require screenshots on pull requests.
- Claude Code and Codex: included in the plugin.
- Grok and Cursor:
uploads installadds 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 createopens 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 hosted MCP server also serves them as skill:// resources, so a client that supports MCP
skills picks them up without installing anything.
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. list_activity and list_repo_files list recent tagged files by pull request or by repo, and only this server has them. In a sandbox with a shell, sign_upload_url uploads files from disk. |
For auth, scopes, and every tool’s parameters, see the MCP server reference.
To use the local server instead of the hosted one:
claude mcp add uploads -- uploads mcpcodex mcp add uploads -- uploads mcp