How to Upload Images to GitHub from Claude Code

February 9, 2026

The problem

Claude Code can take screenshots of your app, generate diagrams, and produce images. But when it's time to add them to a GitHub PR description or issue comment, there's a problem: ![](./local-file.png) doesn't work. GitHub needs a hosted URL.

GitHub has no public API for uploading images. The browser uses an undocumented S3 presigned URL flow that isn't available to CLI tools. This has been a top feature request for years with no resolution.

img402 solves this. Upload an image, get a public URL, embed it in markdown. One curl command, no account, no API key.

Option 1: Free tier (no wallet needed)

The fastest path. Upload any image under 1MB and get a URL that lasts 7 days — plenty for PR reviews.

curl -s -X POST https://img402.dev/api/free \
  -F image=@/tmp/screenshot.png

{
  "url": "https://i.img402.dev/aBcDeFgHiJ.png",
  "id": "aBcDeFgHiJ",
  "contentType": "image/png",
  "sizeBytes": 182400,
  "expiresAt": "2026-02-16T00:00:00.000Z"
}

Paste the url into any GitHub markdown:

![Screenshot of the login page](https://i.img402.dev/aBcDeFgHiJ.png)

Option 2: Paid tier ($0.01 for 1 year)

For images you want to persist — documentation screenshots, architecture diagrams, anything linked from a README. $0.01 USDC per upload, 5MB max, 1-year retention.

This uses the Payments MCP tool to pay via x402 and a two-step flow to keep binary data out of the agent's context window:

# The Payments MCP tool handles x402 payment automatically
POST /api/upload/token
# → {"token": "a1b2c3d4e5...", "expiresAt": "..."}

curl -s -X POST https://img402.dev/api/upload \
  -H "X-Upload-Token: a1b2c3d4e5..." \
  -F image=@/tmp/screenshot.png

Full workflow: screenshot to PR

Here's what happens when you ask Claude Code to "take a screenshot and add it to the PR":

1. Capture — Claude takes a screenshot using screencapture (macOS) or another tool
2. Resize if needed — If over 1MB, scale down with sips -Z 1600 /tmp/screenshot.png
3. Upload — curl -s -F image=@/tmp/screenshot.png https://img402.dev/api/free
4. Embed — Inserts ![Screenshot](https://i.img402.dev/...) into the PR body with gh pr edit

The entire flow takes a few seconds and the image is immediately visible in the PR.

Add it as an agent skill

You can teach your AI agent to do this automatically by installing the github-image-hosting skill. It works with Claude Code, Codex, OpenClaw, and any agent that reads SKILL.md files.

The quickest way to install:

npx skills add img402/skills

Or copy the skill directly into your agent's skills directory:

# Clone and copy the skill
git clone https://github.com/img402/skills.git /tmp/img402-skills
cp -r /tmp/img402-skills/skills/github-image-hosting ~/.claude/skills/

Here's what the skill teaches the agent:

---
name: github-image-hosting
description: >
  Upload images to img402.dev for embedding in GitHub
  PRs, issues, and comments. Triggers: "screenshot this",
  "attach an image", "add a screenshot to the PR".
---

# Image Upload for GitHub

Upload an image to img402.dev and embed the URL in
GitHub markdown.

## Workflow

1. Get image (existing file or screencapture)
2. If over 1MB, resize: `sips -Z 1600 file.png`
3. Upload: `curl -s -X POST https://img402.dev/api/free
   -F [email protected]`
4. Embed the returned `url` in markdown:
   `![Description](https://i.img402.dev/id.png)`

## Constraints

- Max 1MB (free tier limit)
- 7-day retention (fine for PR reviews)
- Formats: PNG, JPEG, GIF, WebP
- No auth required

With the skill installed, your agent will automatically upload images to img402 whenever it needs to embed one in a GitHub context — no manual prompting needed.

Shell one-liner

For quick use outside Claude Code, add this to your shell profile:

# Upload an image and copy the URL
ghimg() { curl -sF image=@"$1" https://img402.dev/api/free | jq -r .url; }

Usage:

ghimg screenshot.png
# → https://i.img402.dev/aBcDeFgHiJ.png

FAQ

How long do images last?

Free tier: 7 days. Paid tier: 1 year. Free tier is designed for PR reviews and temporary sharing. Use paid for anything permanent.

What's the size limit?

Free tier: 1MB. Paid tier: 5MB. If your image is over the limit, resize with sips -Z 1600.

Do I need an account?

No. No account, no API key, no sign-up. Just send the request.

Is this free?

The free tier is free with no strings attached. The paid tier costs $0.01 USDC per upload via x402.