repo-visuals — Claude Code plugin: what it does, how to install
repo-visuals generates animated GIF or static PNG hero graphics for repository README files directly from codebase analysis.
MIT ★ 20 updated 2026-10-15
/plugin marketplace add anthropics/claude-plugins-community
/plugin install repo-visuals@claude-communityWhat repo-visuals does
repo-visuals scans a codebase to suggest fitting README hero graphics, focusing on terminal demos or software interfaces. After analyzing the project, it generates custom HTML, launches a browser preview, and exports the finished file to your working directory.
Internal exports rely on capture.js and screenshot.js. You can pick between three conversational tiers: fully automatic, manual, or the default semi-automatic flow. Dev mode logs scorecard ratings.
Rendering animated files requires ffmpeg and ffprobe installed on your path alongside Node.js 18+. Capturing will fail outright unless you run npm install inside the plugin cache directory to download Puppeteer's Chromium bundle.
What it helps with
- generate an animated terminal GIF for a README
- create a static PNG hero visual matching repo identity
- preview and adjust HTML scenes in a browser before export
- benchmark visual quality through automated scorecards
Example prompts for the agent
- Generate a hero GIF for this repo: https://github.com/owner/name
- Generate a hero GIF for this repo in dev mode: https://github.com/owner/name
- Run retro on my repo-visuals evaluations
How to install repo-visuals
Plugin marketplace
/plugin marketplace add anthropics/claude-plugins-community/plugin install repo-visuals@claude-communityStep by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own
Questions about repo-visuals
How to install repo-visuals in Claude Code?
Run /plugin marketplace add anthropics/claude-plugins-community, then run /plugin install repo-visuals@claude-community, and restart your Claude Code session.
What does repo-visuals do?
It scans a target repository, writes bespoke HTML for a README hero visual, previews it in your browser, and renders animated GIFs, PNGs, or SVGs.
What system dependencies must be installed manually?
You need Node.js 18+ along with ffmpeg and ffprobe in your system path. You also need to run npm install inside the plugin cache directory so Puppeteer can download Chromium.
Source text
repo-visuals · MIT
# repo-visuals

A Claude Code plugin for designing **bespoke GitHub README hero visuals** — **animated GIF**, **static PNG**, or **animated SVG** — for any open-source repository.
The plugin scans the target repo, recommends a format that fits its identity (terminal demo, product UI, brand-first wordmark, banner, diagram-as-hero), generates bespoke HTML through a structured discovery dialog, previews it in your browser, and exports a retina-quality artifact ready to drop into the README.
### Heroes shipped with this skill
<table>
<tr>
<td width="50%" valign="top">
<sub><a href="https://github.com/htmlhint/HTMLHint"><b>htmlhint/HTMLHint</b></a></sub>
<a href="https://github.com/htmlhint/HTMLHint"><img src="https://raw.githubusercontent.com/htmlhint/HTMLHint/main/website/src/assets/img/hero.gif?v=retina" alt="HTMLHint hero"></a>
</td>
<td width="50%" valign="top">
<sub><a href="https://github.com/gui-cs/Terminal.Gui"><b>gui-cs/Terminal.Gui</b></a></sub>
<a href="https://github.com/gui-cs/Terminal.Gui"><img src="https://raw.githubusercontent.com/gui-cs/Terminal.Gui/develop/docfx/images/hero.gif" alt="Terminal.Gui hero"></a>
</td>
</tr>
<tr>
<td width="50%" valign="top">
<sub><a href="https://github.com/kunwar-shah/claudex"><b>kunwar-shah/claudex</b></a></sub>
<a href="https://github.com/kunwar-shah/claudex"><img src="https://raw.githubusercontent.com/kunwar-shah/claudex/main/screenshots/hero.gif" alt="claudex hero"></a>
</td>
<td width="50%" valign="top">
<sub><a href="https://github.com/rullerzhou-afk/clawd-on-desk"><b>rullerzhou-afk/clawd-on-desk</b></a></sub>
<a href="https://github.com/rullerzhou-afk/clawd-on-desk"><img src="https://raw.githubusercontent.com/rullerzhou-afk/clawd-on-desk/main/assets/hero.gif" alt="clawd-on-desk hero"></a>
</td>
</tr>
<tr>
<td width="50%" valign="top">
<sub><a href="https://github.com/affaan-m/everything-claude-code"><b>affaan-m/everything-claude-code</b></a></sub>
<a href="https://github.com/affaan-m/everything-claude-code"><img src="https://raw.githubusercontent.com/affaan-m/everything-claude-code/main/assets/hero.png" alt="everything-claude-code hero"></a>
</td>
<td width="50%" valign="top">
<sub><a href="https://github.com/emtyty/ast-graph"><b>emtyty/ast-graph</b></a></sub>
<a href="https://github.com/emtyty/ast-graph"><img src="https://raw.githubusercontent.com/emtyty/ast-graph/master/docs/ast-graph-demo.gif" alt="ast-graph hero"></a>
</td>
</tr>
</table>
[Full showcase →](./SHOWCASE.md)
## Install
```
/plugin marketplace add livlign/claude-skills
/plugin install repo-visuals@livlign
```
After install, restart Claude Code (or start a new session) so the plugin's skills are discovered.
## Dependencies (install these yourself)
The plugin install does **not** install these — you need them on your system before running:
- **Node.js 18+**
- **puppeteer** — run `npm install` once inside the plugin directory. This downloads ~170 MB of Chromium the first time.
- **ffmpeg** + **ffprobe** (for GIF export and code-evaluated scorecard rows) — `brew install ffmpeg` / `apt install ffmpeg` / `choco install ffmpeg`.
- **gifsicle** *(optional)* — enables palette-size checks in `scripts/evaluate.js`.
`npm install` runs from the plugin's cache directory after install. If you can't find it, use `/plugin` to locate the install path, then `cd` into it and run `npm install`.
## How to run
### Standard run (no scorecard)
> Generate a hero GIF for this repo: https://github.com/owner/name
Claude asks which operating mode to use (see below), runs discovery → build → preview → export → output, and stops. No evaluation is collected.
A run feels like this:
```
You: Generate a hero GIF for this repo: https://github.com/owner/name
Claude: [scans repo] Inferred CLI tool — `bin/` entry, README opens with a $ npx line.
Recommending an animated terminal demo at 1200×675. Which mode — Auto / Semi / Manual?
You: Semi
Claude: [proposes 3 scenarios] Pick one, or describe a different angle.
You: #2, but make the final frame land on the success state for longer.
Claude: [builds HTML, opens preview in browser] Looks right? Any copy/timing tweaks?
You: ship it
Claude: → ./hero.gif (1200×675, 4.2s, 1.8 MB)
```
Final artifact lands in your current working directory. In dev mode, an evaluation row is appended to `./evaluations/runs/<date>-<slug>.md`.
### Dev run (with scorecard)
> Generate a hero GIF for this repo in dev mode: https://github.com/owner/name
Dev mode enables Phase 6 — a 4-rater scorecard (User / Claude / Code / AI-vision-blind). The scorecard is written to `./evaluations/runs/<YYYY-MM-DD>-<slug>.md` in your **current working directory** (not the plugin cache, which is wiped on `/plugin update`).
Enable dev mode either by saying *"dev mode"* in the prompt, or by setting `REPO_VISUALS_DEV=1` in the environment.
### Retro — improve the skill from logs
After you have a handful of dev-mode runs logged:
> Run retro on my repo-visuals evaluations
The `repo-visuals-retro` skill reads `./evaluations/runs/*.md`, spots patterns, and proposes diffs against the main skill. It proposes — it does not auto-apply.
## Operating modes
Every run, the skill asks which mode to use. This is about **how many decisions Claude asks you to make** — it does not relax craft rules.
| Mode | What **you** decide | What **Claude** decides silently | Phase 6 scorecard | Typical back-and-forths |
|---|---|---|---|---|
| **Auto** | nothing | everything (format, scenario, vibe, audience, dimensions, copy, ship) | Code + AI + Claude rows only (no User ratings) | 0 |
| **Semi-auto** _(default)_ | output format (GIF/PNG/SVG/HTML), one preview-and-iterate review | scenario, vibe, audience, dimensions, copy | full 4-rater scorecard | ~3 |
| **Manual** | every decision point | nothing (Claude still suggests and recommends) | full 4-rater scorecard | 8–12 |
Any mode can be upgraded mid-run — say *"stop, switch to semi"* and Claude resumes from the nearest unanswered decision point.
**Note:** operating mode (Auto/Semi/Manual) and dev mode are independent. Dev mode is about whether Phase 6 runs; operating mode is about conversation density.
## Layout
- [`skills/repo-visuals/SKILL.md`](./skills/repo-visuals/SKILL.md) — main skill (discovery → build → preview → export → output → evaluate).
- [`skills/repo-visuals/craft/`](./skills/repo-visuals/craft/) — headline patterns, reference gallery, template HTML.
- [`skills/repo-visuals/scripts/`](./skills/repo-visuals/scripts/) — `capture.js` (GIF), `screenshot.js` (PNG), `evaluate.js` (code-evaluated scorecard). Animated SVG has no capture script — the source `.svg` file is hand-authored and shipped as-is.
- [`skills/repo-visuals-retro/SKILL.md`](./skills/repo-visuals-retro/SKILL.md) — retrospective meta-skill, on-demand.
- [`SHOWCASE.md`](./SHOWCASE.md) — merged hero visuals produced with this skill; open a PR to add yours.
© livlign · MIT · livlign/claude-skills