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 up to 10MB — and if it's 1MB or under (most screenshots are), the URL is permanent. Free, no wallet.

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": null
}

Paste the url into any GitHub markdown:

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

Option 2: Paid tier ($0.01, permanent, up to 10MB)

For larger images you want to persist — full-resolution screenshots, architecture diagrams, anything linked from a README. $0.01 USDC buys permanent hosting for any image up to 10MB, backed by the 90-day shutdown-notice guarantee in our Terms.

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            # $0.01 / permanent
# → {"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 10MB (free tier limit)
- Images ≤1MB are permanent; 1-10MB last 30 days
- 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 images 1MB or under: permanent. Free images 1–10MB: 30 days. Paid ($0.01 USDC): permanent and guaranteed, any size up to 10MB.

What's the size limit?

10MB on all tiers. If your image is over the limit, resize with sips -Z 1600. (Under 1MB it's hosted permanently — worth resizing for that alone.)

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 — permanent under 1MB. Permanent hosting for larger images costs $0.01 USDC per upload via x402.