<div align="center">

🥒 macro-pickle

<img src="https://readme-typing-svg.demolab.com?font=JetBrains+Mono&weight=700&size=22&pause=1000&color=6366F1&center=true&vCenter=true&multiline=true&repeat=true&width=640&height=80&lines=Local+AI+Creative+Tooling+%7C+No+Database;Image+%2B+Video+Gen+%E2%9A%A1+Typed+Prompt+Engine;Gemini+%E2%80%A2+Imagen+%E2%80%A2+fal.ai+%E2%80%A2+Veo+%E2%80%A2+Kling" alt="Typing SVG" />

<img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="rainbow line" width="100%"/>

🥒 Local, database-free AI creative tooling — image & video generation plus a typed, brand-aware Prompt Engine, driven through Claude. No database, no web app. Big dill. 🌶️

</div>

👀 What it is

macro-pickle is a command-line + MCP toolkit for generating brand-aware imagery and video and for engineering the prompts behind them. There is no database and no web app — every rail writes files to disk, and finalized prompts are exported as copy-paste markdown you can drop into any notes vault.

It runs through Claude — CLI scripts via tsx, a desktop MCP server, and Claude Code skills/commands — with Google (Gemini vision, Imagen, Veo, Nano Banana) and fal.ai (FLUX et al., Kling video) as the generation backends.

🚦 Quick start (0 to pickle in 60 seconds 🏃💨)

Prerequisites: Node 20+, pnpm, and at least one API key.

git clone https://github.com/MrJPTech/macro-pickle.git
cd macro-pickle
pnpm install

cp .env.example .env.local        # then add your keys (see below)
pnpm lint                         # tsc --noEmit — verifies the install
pnpm prompt --brands              # list the installed brand profiles
pnpm img "a neon pickle mascot, dark studio bg"     # Imagen → PNG on disk

🔑 Keys

Everything is optional except the backend you actually use — nothing is required to build prompts, only to render pixels.

Variable	Needed for	Get one
GOOGLE_API_KEY	Gemini vision/OCR, Imagen, Veo, Nano Banana, Omni Flash	ai.google.dev
FAL_KEY	Kling video + FLUX / Recraft / Ideogram / SD3.5 images	fal.ai
BYTEPLUS_API_KEY · RUNWAY_API_KEY · REPLICATE_API_TOKEN	Optional extra video providers via the model registry	see .env.example

📁 Where output goes

All paths are yours to set — the defaults are all repo-relative, so a fresh clone works with no configuration.

Variable	Default	What it controls
MACRO_PICKLE_EXPORT_DIR	./generated-images	Where rendered images/clips land. Point it at a synced folder (iCloud/Drive/Dropbox) to review on your phone.
MACRO_PICKLE_PROMPT_VAULT	./exported-prompts	Where --save writes finalized prompt notes. Point it at an Obsidian/Logseq vault to collect them there.
MACRO_PICKLE_OMNI_DIR	falls back to export dir	Default output for pnpm omni video edits.
MACRO_PICKLE_BRANDS_DIR	content/brands	Where brand profiles are loaded from — keep private brands outside the repo.

<details> <summary><b>⚡ Scripts (buttons to mash 🎮)</b></summary>

Command	What it does
pnpm prompt	Build image/video prompts via the Prompt Engine (--image/--video, --brand, --json, --save, --gen)
pnpm img	Imagen 4.0 reference-image generation → MACRO_PICKLE_EXPORT_DIR
pnpm fal	fal.ai image models (FLUX / Recraft / Ideogram / SD3.5) — Prompt Engine parity
pnpm nano	Nano Banana face-lock generation from reference photos (likenesses you have rights to)
pnpm veo	Google Veo video — text-to-video, image-to-video, and --refs ASSET identity lock
pnpm kling	Kling video via fal.ai — i2v / t2v / start+end interpolation
pnpm describe	Gemini vision: product OCR + in-use scene recommendation (UGC rail); --paddle for the local OCR sidecar
pnpm ocr	Optional local PaddleOCR sidecar (high-recall small/CJK text + geometry)
pnpm analyze-video	Describe a reference/competitor clip for mirroring
pnpm scene:new/refs/select/analyze/video	Media pipeline — two-stage: text → reference frames → curate → re-prompt to video (docs/media-pipeline.md)
pnpm rank-skus · pnpm gen-clips	Store batch clips — rank a store's SKUs by sales → generic reference→video batch (Veo free + Kling paid), spend-gated
pnpm omni · pnpm seedance · pnpm wan	Gemini Omni Flash conversational video editing · Seedance · Wan video rails
pnpm models	Browse / select across the cross-provider video-model registry
pnpm mcp:image	Run the macro-pickle-images desktop MCP server
pnpm lint	Type-check the whole toolkit (tsc --noEmit)

</details>

<details> <summary><b>🎨 Prompt Engine (the secret sauce 🧪)</b></summary>

scripts/lib/prompts/ turns the methodology in content/knowledge/PROMPT-COOKBOOK.md (synthesized from a fleet of reference repos) into typed, deterministic builders — no DB required:

Piece	What it does
buildImagePrompt	Nano Banana "Perfect Prompt" formula — Subject + Action + Context + Composition + Lighting + Style
buildVideoPrompt	Seedance/Veo "Director Brief" — Scene · Subject · Camera · Action · Audio · Pacing + time-segmented beats + on-screen captions
Brand profiles	content/brands/*.json — style, palette, prefer/avoid, suffix, IP-safe cast proxies; auto-applied via --brand
UGC layer	scripts/lib/prompts/ugc.ts — faceless short-form selling formats (hero still → lifestyle still → 9:16 spot)
lintScene	Continuity & IP-safety linter — single-beat, fixed-camera, stationary-cycle, atmospherics

📓 Export convention: finalized prompts are written as copy-paste markdown — pnpm prompt … --save, or save: true on the MCP build tools. They land in ./exported-prompts/ unless you point MACRO_PICKLE_PROMPT_VAULT at a notes vault.

</details>

<details> <summary><b>🎬 Media Pipeline — idea → references → video (the <code>scene:*</code> flow 🎞️)</b></summary>

The two-stage workflow at the heart of the toolkit: turn an idea into reference images, curate the winners, then re-prompt them into video — across Nano Banana / Imagen / Veo / Kling / Gemini. A local scene.json manifest tracks every prompt, frame, and clip (full walkthrough).

pnpm scene:new    my-scene        # scaffold scene.json (reference + video prompts)
pnpm scene:refs   my-scene        # Stage 1 — generate reference-frame candidates
pnpm scene:select my-scene <ids>  # curate the keepers
pnpm scene:analyze my-scene       # (optional) Gemini grounding of the picks
pnpm scene:video  my-scene        # Stage 2 — selected frames → Veo clip

Piece	What it does
scene-store	Local JSON manifest — prompts, frames, selections, clips per scene
PromptEnhancer	Gemini chain-of-thought prompt rewriter (+ exemplar banks) that directs your idea
groundFrames	Image → understanding feedback loop — keeps Stage 2 on-subject / on-brand
Veo modes	ingredients (ASSET refs) · firstLast (first→last frame) · firstFrame (i2v)

Built on the same scripts/lib/ clients as the rest of the toolkit — one set of model clients, no duplication.

</details>

<details> <summary><b>🤖 MCP server, skills & commands (Claude's toolbelt 🛠️)</b></summary>

• MCP (macro-pickle-images, pnpm mcp:image) — exposes build_image_prompt, build_video_prompt, describe_product, build_ugc_spot, analyze_reference_video, lint_scene, generate_image, generate_video to Claude Desktop.
• Skills (.claude/skills/) — openmontage-video-prompting (cinematography), ugc-shortform-prompting (selling layer), character-lock (identity / face lock).
• Commands (.claude/commands/) — /pickle-prompt · /pickle-ugc · /pickle-pipeline (scene:*) · /pickle-winners → /pickle-clips (rank winners → batch clips) · /pickle-ref (clean references) · /pickle-describe (OCR + scene rec) · /pickle-character (face-lock) · /pickle-brand (new brand profile).

</details>

<details> <summary><b>🛠️ Stack (what's under the hood 🏎️)</b></summary>

Layer	Technology
Language / runtime	TypeScript (strict, ESM) on Node via tsx
Image / video	@google/genai (Gemini · Imagen · Veo · Nano Banana) · @fal-ai/client (FLUX · Kling)
MCP	@modelcontextprotocol/sdk
Validation	zod
Optional OCR sidecar	Python + PaddleOCR (scripts/py/, opt-in)

</details>

<details> <summary><b>📂 Layout (where the bodies are buried ⚰️🗺️)</b></summary>

macro-pickle/
├── scripts/
│   ├── lib/                # generation cores: imagen, fal, veo, kling, nano-banana, vision, paddleocr
│   │   ├── prompts/        # the Prompt Engine (builders, brand, scene, export, ugc, lint)
│   │   └── pipeline/       # scene-store + prompt-enhancer + exemplars + presets
│   ├── pipeline/           # scene:new/refs/select/analyze/video CLI
│   ├── generate-*.ts       # pnpm img / fal / nano / veo / kling
│   ├── build-prompt.ts     # pnpm prompt
│   ├── describe-product.ts · ocr.ts · analyze-video.ts   # vision / OCR rails
│   ├── gen-clips.ts · rank-skus.ts   # store batch-clip rails
│   └── py/                 # optional PaddleOCR sidecar
├── mcp/image-server/       # macro-pickle-images desktop MCP
├── content/
│   ├── brands/             # brand profiles (*.json) — `quiet-desk` is the worked example
│   ├── briefs/             # scene briefs — `example-logo/` shows the format
│   ├── clip-scenes/        # per-store batch-clip scene configs (`example-store.json`)
│   └── knowledge/          # PROMPT-COOKBOOK.md methodology
└── .claude/                # skills + slash commands

</details>

📜 License

MIT — see LICENSE. Free as a pickle at a deli counter. 🥪

<img src="https://raw.githubusercontent.com/andreasbm/readme/master/assets/lines/rainbow.png" alt="rainbow line" width="100%"/>

<div align="center">

🧑‍🍳 Lovingly brined by MrJPTech · a PRSMTECH project

📅 Last Updated: July 2026 · Status: 🎨 Local database-free creative toolkit — image + video gen, Prompt Engine, MCP · Vibe: kind of a big dill 🥒

<img src="https://capsule-render.vercel.app/api?type=waving&color=gradient&customColorList=6,11,20&height=100&section=footer" width="100%" />

</div>