Documentation
RepoCard designs social preview images for GitHub repositories. The social preview is the image shown when someone shares your repository link on X, LinkedIn, Slack, Discord, iMessage and elsewhere.
Quick start
- Paste a repository link on the home page.
- Pick one of the four concepts and fine-tune it if you like.
- Click Download PNG, then follow Add it to GitHub.
Every card is also a stable URL you can embed anywhere:
/card/OWNER/REPO.png
/card/OWNER/REPO.png?variant=2&palette=paper
Add it to GitHub
You need admin access to the repository.
- Open the repository on GitHub and click Settings (or go to
https://github.com/OWNER/REPO/settings). - On the General page, find Social preview near the top.
- Click Edit → Upload an image… and choose the PNG.
- That's it. GitHub saves it immediately.
GitHub recommends 1280×640 pixels and under 1 MB, which is exactly what RepoCard produces. To remove a custom image later, use Edit → Remove image.
openGraphImageUrl, usesCustomOpenGraphImage) but not change it. The CLI automates the upload in your own browser instead.Seeing an old image? X, LinkedIn, Slack and Facebook cache link previews for days. Most offer a way to refresh a URL, for example LinkedIn's Post Inspector.
Bulk export
The bulk page lists every public repository of a user or organization with its card, a Settings ↗ link for each, and Download all (ZIP). The ZIP contains one PNG per repository plus an index.html with every settings link.
AI designs asks the model to design each repository (a few seconds each, then cached). Fast uses stored designs if they exist, otherwise deterministic ones, and never calls the model.
CLI
The repocard CLI needs Node.js 20 or later. It renders cards on your machine with the same engine as the website, so it works without any server.
# one repository
npx repocard card vercel/next.js
# every public repository of an account, into ./social-previews
npx repocard bulk your-username
# which repositories already have a custom preview
npx repocard status your-username
Upload to every repository automatically
repocard apply does the upload GitHub doesn't offer an API for. It opens a real browser window, you sign in to GitHub yourself, and it uploads each card through the normal settings page.
# 1. install the browser automation library once
npm install -g playwright && npx playwright install chromium
# 2. dry run: renders cards and shows the plan, uploads nothing
npx repocard apply your-username
# 3. upload
npx repocard apply your-username --yes
- Safe by default. Without
--yesnothing is uploaded. Repositories that already have a custom preview are kept unless you pass--overwrite. - Your session stays local. You sign in inside the browser window. RepoCard never sees your password or cookies. The profile is stored at
~/.repocard/browser(change it with--profile). - Verified. With a GitHub token (
GITHUB_TOKEN,GH_TOKEN, orgh auth login), RepoCard checks through the API that each upload took effect and skips repositories where you lack admin access. - Best effort. It drives GitHub's web UI, so a redesign of the settings page can break it. When an upload fails, RepoCard prints the settings link and the PNG path so you can finish by hand.
| Option | Description |
|---|---|
-o, --out | Output file (card) or directory (bulk). |
-v, --variant | Design concept 1-4. Default 1. |
--layout --palette --font --tagline | Override parts of the design. |
--endpoint | Use a RepoCard server (AI designs) instead of rendering locally. Also REPOCARD_URL. |
--forks --archived | Include forks or archived repositories. |
--yes | apply: actually upload. |
--overwrite | apply: replace existing custom previews. |
--headless | apply: no window (after signing in once). |
--delay | apply: milliseconds between repositories. Default 2000. |
For AI designs without a server, set LLM_BASE_URL, LLM_API_KEY and LLM_MODEL to any OpenAI-compatible endpoint (Groq, OpenRouter, Gemini, Together, Ollama).
GitHub Action
Keeps a fresh card committed in your repository and can show it as a README banner. Add .github/workflows/social-preview.yml:
name: Social preview
on:
workflow_dispatch:
schedule:
- cron: '0 6 * * 1'
permissions:
contents: write
jobs:
card:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: nirholas/RepoCard@v1
with:
readme-banner: true
| Input | Default | Description |
|---|---|---|
variant | 1 | Design concept 1-4. |
layout, palette, font | Optional overrides. | |
path | .github/social-preview.png | Where to write the image. |
readme-banner | false | Insert or update a banner between <!-- repocard:start --> markers. |
commit | true | Commit and push changes. |
endpoint | RepoCard server for AI designs. Without it, cards render on the runner. |
The Action can't set the social preview itself (no API). It writes the image and a job summary with the settings link; upload once, or run repocard apply.
HTTP API
No key required. All endpoints are read-only and send CORS headers. Machine-readable spec: /openapi.json.
| Endpoint | Returns |
|---|---|
GET /card/{owner}/{repo}.png | 1280×640 PNG. Errors return a PNG explaining the problem, with the matching status code. |
GET /card/{owner}/{repo}.svg | The same card as SVG. |
GET /api/v1/cards/{owner}/{repo} | The four concepts with specs, PNG/SVG URLs, Markdown, HTML and setup steps. |
POST /api/v1/cards | Same, from {"repo": "any GitHub URL", "refresh": true}. refresh asks for new concepts. |
GET /api/v1/users/{owner}/repos | Public repositories with card and settings URLs. ?forks=1&archived=1&limit=300. |
GET /api/v1/options | Every layout, palette, font, background and query parameter. |
POST /mcp | MCP server for AI agents. |
Card parameters
| Parameter | Values |
|---|---|
variant | 1-4 (default 1) |
layout | spotlight, split, editorial, terminal, poster, minimal |
palette | midnight, obsidian, aurora, ember, nebula, ocean, forest, terminal, crimson, gold, paper, snow, mint, blush, sand, sky |
font | modern, geometric, technical, editorial, friendly, expressive |
background | aurora, grid, dots, diagonal, rings, solid |
mark, emoji | avatar, monogram, emoji, none; emoji=🚀 with mark=emoji |
accent | Hex color without #, adjusted automatically if illegible |
title, tagline, chips | Text overrides; chips are comma-separated (max 3) |
stats=0, owner=0 | Hide stars/forks/language/license or the owner |
mode=fast | Never call the AI; use stored or deterministic designs |
curl -o card.png "/card/vercel/next.js.png?variant=2"
curl "/api/v1/cards/vercel/next.js"
Images are cached at the edge for several hours. Limits apply to new renders per IP address; cached images are unaffected.
AI agents (MCP)
RepoCard runs a Model Context Protocol server over Streamable HTTP at /mcp. No authentication is needed.
Claude Code
claude mcp add --transport http repocard /mcp
Cursor (.cursor/mcp.json)
{ "mcpServers": { "repocard": { "url": "/mcp" } } }
VS Code (.vscode/mcp.json)
{ "servers": { "repocard": { "type": "http", "url": "/mcp" } } }
Claude Desktop and other stdio clients
{ "mcpServers": { "repocard": { "command": "npx", "args": ["-y", "mcp-remote", "/mcp"] } } }
Tools
| Tool | What it does |
|---|---|
create_social_preview | Designs and renders a card. Returns the PNG inline, its URL, the design, and setup steps. Accepts the same overrides as the image URL. |
get_design_concepts | All four concepts with rationale and URLs. refresh asks for new ones. |
list_account_cards | Every public repository of an account with card and settings URLs. |
how_to_set_social_preview | Step-by-step instructions and automation options. |
get_design_options | The full design vocabulary. |
Agents that prefer plain HTTP can read /llms.txt and /openapi.json.
Design system
The model never writes free-form markup. It picks from a curated vocabulary, and code renders the result:
- Layouts: spotlight (centered), split (text and a visual panel), editorial (magazine serif), terminal (code window), poster (huge type), minimal (quiet and precise).
- Palettes: ten dark and six light schemes. Every palette meets WCAG contrast (7:1 for text, 4.5:1 for secondary text), and custom brand accents are adjusted until they're legible.
- Type: Inter, Space Grotesk, JetBrains Mono, Instrument Serif, Sora and Bricolage Grotesque, all SIL Open Font License. Emoji use Twemoji, and non-Latin scripts load matching Noto fonts on demand.
- Copy: the model writes a one-line tagline and up to three keywords. Text is length-limited and cleaned before rendering.
If the model is unavailable, slow, or returns something unusable, RepoCard falls back to deterministic designs derived from the repository's language and metadata, so a request never fails because of the AI.
Self-hosting
RepoCard is a single Cloudflare Worker with static assets.
git clone https://github.com/nirholas/RepoCard && cd RepoCard
npm install
npx wrangler login
npx wrangler kv namespace create DESIGNS # paste the id into wrangler.jsonc
npx wrangler secret put GITHUB_TOKEN # fine-grained token, public repositories, read-only
npm run deploy
| Setting | Kind | Purpose |
|---|---|---|
AI | Binding | Workers AI. Remove to use deterministic designs only. |
DESIGNS | KV binding | Stores designs so each repository keeps a stable look. |
RENDER_LIMITER, AI_LIMITER | Rate limit bindings | Per-IP limits for new renders (60/min) and AI generations (10/min). |
GITHUB_TOKEN | Secret | Raises GitHub API limits from 60 to 5,000 requests/hour. Strongly recommended. |
AI_PROVIDER | Variable | workers-ai (default), openai-compatible, or none. |
AI_MODEL | Variable | Workers AI model. Default @cf/meta/llama-3.3-70b-instruct-fp8-fast. |
LLM_BASE_URL, LLM_MODEL, LLM_API_KEY | Variables / secret | Any OpenAI-compatible endpoint when AI_PROVIDER=openai-compatible. |
PUBLIC_URL | Variable | Canonical origin used in returned URLs. Defaults to the request origin. |
Before deploying your own copy, edit wrangler.jsonc: point routes at your domain (or remove them and set "workers_dev": true) and set PUBLIC_URL to match.
Use a custom domain for production: the Workers Cache API, which caches rendered images, doesn't run on *.workers.dev.
Privacy & security
- RepoCard only reads public repository data through the GitHub API. It never asks for access to your account and never writes to GitHub.
- It stores the generated design (layout, palette and text) per repository. It doesn't store IP addresses beyond the transient rate limiter.
- README content is passed to the model as untrusted data. Model output is restricted to a fixed vocabulary and short, cleaned text.
- Only GitHub's avatar host can be fetched for images. SVG responses carry a restrictive Content-Security-Policy.
- Report vulnerabilities privately; see SECURITY.md.
Troubleshooting
"Repository not found"
The repository is private, renamed, or misspelled. RepoCard only supports public repositories.
"Too many requests"
New renders are limited per IP address. Wait a minute; cached cards keep working.
The badge says "Designed from metadata"
The AI was busy or unavailable, so RepoCard used deterministic designs. Click New concepts later to try the AI again.
repocard apply can't find the upload control
GitHub may have changed its settings page. Upload the printed PNG by hand and open an issue.