pinmuse

An open-source AI design agent that studies Pinterest and makes the post.

Posters, Instagram stories, carousels and pins with real typography, from one sentence. Agent Skill, CLI and MCP server for Claude Code, Codex, Gemini CLI and any MCP client.

Website · Gallery · Install · Usage · Image models · FAQ

---

You ask your agent for "a dark-academia story for my book club". pinmuse searches Pinterest, reads the palette, light and mood of the pins it finds, writes an image prompt that leaves room for type, generates the picture with whatever model you have, and sets the headline itself. You get a finished file, a caption with hashtags, and credits for the pins it learned from.

No screenshots, no copy-pasting pins, no design app.

Gallery

Each design is a single pinmuse create command. Images by gpt-image-2.5-flare; layout and type by pinmuse.

Carousels get a new photo on every slide: a cover, numbered slides and an end card. Give each slide a subject and pinmuse generates a picture for it.

The raw generations underneath each design are in outputs/photos. More on the website.

Install

curl -fsSL https://raw.githubusercontent.com/prantikmedhi/pinmuse/main/install.sh | bash

This installs the CLI and links the skill into every agent it finds (Claude Code, Codex, Gemini CLI, Antigravity, opencode, OpenClaw, Hermes, Cursor). Add --mcp to register the MCP server too.

Agent	Skill	MCP
Claude Code	/plugin marketplace add prantikmedhi/pinmuse → /plugin install pinmuse	included
Codex	ln -s $PWD/skills/pinmuse ~/.codex/skills/pinmuse	codex mcp add pinmuse -- pinmuse mcp
Gemini CLI	gemini extensions install https://github.com/prantikmedhi/pinmuse	included
Antigravity	ln -s $PWD/skills/pinmuse ~/.gemini/antigravity/skills/pinmuse	pinmuse mcp
opencode	ln -s $PWD/skills/pinmuse ~/.config/opencode/skills/pinmuse	{"type": "local", "command": ["pinmuse", "mcp"]}
OpenClaw / Hermes	ln -s $PWD/skills/pinmuse ~/.openclaw/skills/pinmuse	pinmuse mcp
Any MCP client	n/a	copy .mcp.json

CLI only: pip install "pinmuse[mcp] @ git+https://github.com/prantikmedhi/pinmuse"

Usage

Ask your agent:

Make an Instagram story for our Friday rooftop party. Get the vibe from Pinterest: vaporwave sunset.

Or run it yourself:

pinmuse create "rooftop party at sunset" --inspo "vaporwave sunset aesthetic" \
  -t story -f ig-story --title "Sunset Club" --subtitle "Friday • rooftop • 8pm" --cta "RSVP in bio"

pinmuse-out/20261103-201500-sunset-club/
├── story-ig-story.jpg   the post
├── base-1.png           the generated image
├── moodboard.jpg        the pins it learned from
├── caption.txt          caption and hashtags
└── manifest.json        prompt, palette, model, pin credits

Step by step, the way the skill teaches agents to work:

pinmuse suggest   "cozy reading"                 # Pinterest's own related searches
pinmuse moodboard "dark academia library"        # palette, mood, aesthetic, contact sheet
pinmuse generate  "<prompt>" -f ig-post --refs pin1.jpg,pin2.jpg
pinmuse compose   -t quote -f ig-post --image generated.png --title "Paradise is a kind of library."

Carousels take a slides file; each slide's subject becomes its own image:

pinmuse create "salt flat mirror at sunset" -t carousel --slides slides.json --title "Places that look unreal"
# slides.json: [{"title": "Zhangjiajie, China", "body": "Pillars in the fog.", "subject": "sandstone pillars in fog at dawn"}, …]

How it works

1. Explore Pinterest by phrase, pin URL or board URL, signed out and throttled. The official API covers your private boards.
2. Distill the palette, brightness, contrast, warmth and recurring motifs, and match them against 14 aesthetics. The agent also looks at a contact sheet.
3. Prompt for the subject and the learned direction, with empty space where the text will go. The model never draws text.
4. Generate with your model. OpenAI and Gemini can take 2–4 pins as style references.
5. Compose with real fonts, auto-fit, safe zones, grain and your brand kit.
6. Ship the post plus caption.txt and manifest.json with pin credits.

Image models

--provider auto uses the first one configured. pinmuse list providers shows what is set up.

Provider	Setup
OpenAI gpt-image	OPENAI_API_KEY, optional PINMUSE_OPENAI_MODEL
Azure OpenAI	OPENAI_BASE_URL=https://<resource>.openai.azure.com/openai/v1, OPENAI_API_KEY, PINMUSE_OPENAI_MODEL=<deployment>
Gemini (Nano Banana)	GEMINI_API_KEY
Flux on fal / Replicate / Together	FAL_KEY / REPLICATE_API_TOKEN / TOGETHER_API_KEY
Stability	STABILITY_API_KEY
ComfyUI, AUTOMATIC1111, Forge	running locally on the default port
🤗 diffusers	pip install "pinmuse[local]"
Any CLI	PINMUSE_IMAGE_CMD='mflux-generate --prompt {prompt} --output {out}'
None	built-in procedural backgrounds, no key needed

If your agent already has an image tool, it can generate there and run pinmuse compose --image on the result.

Templates and formats

Templates poster magazine story quote polaroid minimal swiss collage palette carousel

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗