@takazudo/pgen

Deterministic visual pattern generator — 36 curated pattern families, ~2,500 registered pattern variants, from geometric tiles to noise-based textures. Same seed always produces the same image.

Install

# Global install
npm i -g @takazudo/pgen

# Or run without installing
npx @takazudo/pgen <slug> [options]

The CLI binary is pattern-gen.

Links

| | | |---|---| | Web app | https://zudo-pgen.app | | Documentation | https://doc.zudo-pgen.app/ | | Manual | https://manual.zudo-pgen.app/ | | CLI reference | https://doc.zudo-pgen.app/docs/cli/ |

Saved compositions are addressed as https://zudo-pgen.app/c/<accountId>/<slug>, and a user's public page as https://zudo-pgen.app/u/<accountId>. Both are accepted directly by pattern-gen fetch.

Images

Single pattern

pattern-gen my-seed
pattern-gen my-seed --type voronoi --size 1200 --color-scheme ocean
pattern-gen my-seed --type hexagonal -c random --out output.png

Key flags:

| Flag | Description | |------|-------------| | --type, -t <name> | Pattern algorithm (default: wood-block). See --list-types. | | --size, -s <px> | Output size in pixels (default: 800) | | --color-scheme, -c <name> | Color scheme name or random. See --list-color-schemes. | | --bg <hex> | Override background color (e.g. #1a1a2e) | | --hue <n> | Hue shift −180 to 180 | | --saturation <n> | Saturation shift −100 to 100 | | --lightness <n> | Lightness shift −100 to 100 | | --contrast <n> | Contrast adjustment −100 to 100 | | --brightness <n> | Brightness adjustment −100 to 100 | | --invert | Invert all palette colors | | --out, -o <path> | Output file path | | --out-dir <dir> | Output directory |

OGP image (1200×630)

Render an OGP config JSON produced by the web viewer:

pattern-gen --ogp-config config.json --out banner.png

Composer image

Render from a Composer config JSON (background pattern + text/image layers):

pattern-gen --composer-config composer.json --out result.png
pattern-gen --composer-config composer.json --assets-dir ./images --out result.png

--assets-dir sets the base directory for resolving relative image paths in the config.

Template

Templates are reusable Composer configs with named fields. Export a template from the web viewer, then fill in the fields at the CLI:

pattern-gen --template my-template.json
pattern-gen --template my-template.json --field "Title=Hello World" --field "Subtitle=2026"
pattern-gen --template my-template.json --width 1920 --height 1080 --out wide.png

Recipe

Recipes are curated presets for common image layouts (title cards, OGP banners, etc.):

# List available recipes
pattern-gen --list-recipes

# Generate from a recipe
pattern-gen --recipe ogp --title "My Post Title" --out card.png
pattern-gen --recipe ogp --title "My Post" --subtitle "A subtitle" --color-scheme ocean
pattern-gen --recipe ogp --title "My Post" --pattern voronoi --font "Inter" --count 3

Recipe flags: --title (required), --subtitle, --pattern, --color-scheme, --font, --layout, --count.

Batch variations

Generate multiple variations of a Composer config or template in one pass:

# Vary pattern and color scheme across 10 outputs
pattern-gen --composer-config composer.json --batch --vary pattern,colorScheme --out-dir ./batch

# Custom count and vary fields
pattern-gen --template card.json --batch --vary colorScheme,titleFont --count 20 --out-dir ./out

# Provide custom pools via JSON file
pattern-gen --composer-config composer.json --batch --vary pattern --vary-from pools.json --out-dir ./out

Valid --vary fields: pattern, colorScheme, titleFont.

Local agent (MCP)

Use Claude Code or Codex to inspect and safely edit an open Composer tab through the local MCP bridge. The loopback development workflow does not require a pattern-gen sign-in:

# Register the pgen MCP server
pattern-gen mcp install --claude
pattern-gen mcp install --codex

# Optional explicit bridge lifecycle controls
pattern-gen bridge --status
pattern-gen bridge --stop

The MCP shim normally starts the bridge on demand. Pair the Composer tab with the one-time code shown by composer_status, keep the code and bearer token private, and leave the trust mode at Review all unless you deliberately choose Co-edit. A production-origin tab first goes through the browser's local-network consent prompt; production-browser support remains verification pending. A dropped connection needs a fresh composer_status code because the bridge does not reconnect automatically. Start with the terminal quickstart, then see the Live Composer local-agent guide for the full reference.

Movies

Quick video export

The --video flag is the fastest way to render an animated pattern to a file. Format is inferred from the extension:

pattern-gen my-seed --type plasma --video out.mp4
pattern-gen my-seed --type plasma --video out.webm
pattern-gen my-seed --type plasma --video out.mp4 --duration 3000 --fps 60

Works with Composer configs too:

pattern-gen --composer-config composer.json --video out.mp4

Note: mp4 and webm encoding requires ffmpeg. If ffmpeg is not on PATH, the CLI falls back to writing a frame-sequence (individual PNG frames) and exits with a warning (exit 0).

Full animation export

--animation gives finer control over the frame pipeline:

# Frame sequence (no ffmpeg needed)
pattern-gen my-seed --type plasma --animation --out-dir ./frames --output-format frame-sequence

# Encoded video
pattern-gen my-seed --type plasma --animation --out-dir ./out --output-format mp4
pattern-gen my-seed --type plasma --animation --out-dir ./out --output-format webm
pattern-gen my-seed --type plasma --animation --out-dir ./out --output-format gif

Animation flags:

| Flag | Description | |------|-------------| | --animation | Enable multi-frame export mode (requires --out-dir) | | --output-format <fmt> | mp4 | webm | gif | frame-sequence (default: frame-sequence) | | --duration, --duration-ms <ms> | Loop duration in milliseconds | | --fps <n> | Frames per second (default: 30) | | --frame-count <n> | Override total frame count (overrides --duration-ms) |

Note: mp4, webm, and gif encoding all require ffmpeg. If ffmpeg is not on PATH, the CLI falls back to frame-sequence with a warning (exit 0).

Utility commands

pattern-gen --list-types          # List all available pattern algorithms
pattern-gen --list-color-schemes  # List all named color schemes
pattern-gen --list-components     # List available component assets
pattern-gen --list-recipes        # List available recipe presets
pattern-gen --help                # Full flag reference

Account & compositions

# Log in with a CLI token (interactive, input is hidden)
pattern-gen login

# Log in with an explicit token
pattern-gen login --token <token>

# Log out
pattern-gen logout

# Fetch a saved composition and render it locally
pattern-gen fetch <url-or-slug>
pattern-gen fetch <url-or-slug> --out result.png --save-config config.json
pattern-gen fetch <url-or-slug> --config-only --save-config config.json

# Push a local composer config as a new composition
pattern-gen push --from composer.json --name "My Composition"
pattern-gen push --from composer.json --update <slug> --public

Website → ideas → selected composition

Keep the website composition as one canonical Composer config with both a square slice and a 1200×630 slice. That gives the CLI one source of truth for the same layers, typography, and pattern while preserving the exact crops each preview surface needs.

First confirm the installed artifact actually contains this workflow:

pattern-gen --help

The root help must list ideas. The currently published npm package may predate that command even when its version matches a development checkout, so do not use the version string alone as the feature check.

# A public URL needs no local account lookup. Capture the canonical config only.
pattern-gen fetch https://zudo-pgen.app/c/<accountId>/<slug> \
  --config-only --save-config source.json

# Build twelve recoverable, seed-only ideas. `seed` is the default; pattern-family
# changes are intentional opt-ins via --vary seed,pattern.
pattern-gen ideas --composer-config source.json --out-dir ./ideas --json

# After visually choosing idea 3, verify its hashes, save its canonical config,
# then upload its exact main, square, and OGP preview artifacts.
pattern-gen push --manifest ./ideas/manifest.json --idea 3 \
  --name "Selected treatment" --with-preview --json

ideas writes a canonical config, rendered slices, three preview artifacts, and a versioned manifest.json per idea. The manifest records SHA-256 hashes, source identity, package/renderer/runtime provenance, and portable inputs. Its config is deterministic; pixel-identical re-renders remain bounded by the renderer, installed fonts, native dependencies, and operating environment.

The preflight fails early for managed app images, local or unpinned remote images, device fonts, and unknown components. Embed assets, use portable font inputs, and use components included in this CLI build before creating a bundle. Unsupported node-renderer effects are reported as fidelity diagnostics.

Manifest verification completes before the first write, but config save and preview upload are two API operations, not one atomic transaction. If preview upload fails, the composition config remains saved. The JSON result reports configSaveStatus: "succeeded", previewUploadStatus: "failed", and the saved slug. Retry the exact selected entry as an update so recovery does not create a duplicate:

pattern-gen push --manifest ./ideas/manifest.json --idea 3 \
  --update "<slug-from-failed-result>" --name "Selected treatment" \
  --with-preview --json

If no exact square or 1200×630 slice exists, previews fall back to deterministic cover crops. Prefer explicit slices when the crop is part of the design. Use --preview-main, --preview-square, or --preview-ogp to select a particular slice by ID (or a unique name).

pnpm pack:smoke validates this release artifact in a fresh temporary consumer project. Publishing a new npm version remains a separate maintainer action and is not required for local proof. For manual testing from a checkout, build and install the local tarball in a throwaway consumer:

pnpm run build
(
  PGEN_PACK_DIR="$(mktemp -d)"
  pnpm pack --pack-destination "$PGEN_PACK_DIR"
  mkdir "$PGEN_PACK_DIR/consumer"
  cd "$PGEN_PACK_DIR/consumer"
  npm init -y
  npm install ../takazudo-pgen-*.tgz
  ./node_modules/.bin/pattern-gen --help
)

Paired Japanese typography swarm

Start from an explicit Composer config rather than a prose-only prompt. Put the square canvas and central wide crop in the same source, keep the title as explicit lines with wrapping disabled, and make the typography settings deliberate. For example, test/fixtures/packed-cli/japanese-typography-swarm.json uses the title モジュラー\nシンセ\n電源入門, 190px bold type, 0.82 line-height, -9.5px tracking (about -0.05em), centered alignment, hard shadow, stroke, and a dark backplate. Its exact Square 1200×1200 and central Wide 1200×630 slices are emitted together.

Use only exact Google Font faces that pass strict preflight. A pool file has the same shape as test/fixtures/packed-cli/japanese-typography-pools.json:

{
  "pattern": ["circuit-traces", "pcb-trace-routing", "truchet"],
  "colorScheme": ["TokyoNight", "Dracula", "Kanagawa Wave"],
  "titleFont": ["Noto Sans JP", "Zen Maru Gothic", "Noto Serif JP", "Kaisei Decol"]
}

Generate the paired candidates with exact selectors:

pattern-gen ideas \
  --composer-config ./source.json \
  --count 100 \
  --vary seed,pattern,colorScheme,titleFont \
  --vary-from ./pools.json \
  --all-slices \
  --preview-main Square \
  --preview-square Square \
  --preview-ogp Wide \
  --out-dir ./ideas \
  --json

# One-off paired contact sheet/index; open the generated review-index.html.
pnpm ideas:index ./ideas/manifest.json

Inspect manifest.json before review: command.options records the exact pools and selectors; provenance.inputs contains strict face, glyph, source, and digest receipts; each idea records its choices and artifact hashes. A quick distribution report needs no pgen-specific tooling:

node -e 'const m=require(process.argv[1]);for(const k of ["pattern","colorScheme","titleFont"]){const n=new Map;for(const i of m.ideas){const v=i.choices[k];n.set(v,(n.get(v)||0)+1)}console.log(k,Object.fromEntries(n))}' ./ideas/manifest.json

Review every candidate's square and wide preview together. pgen produces candidates and provenance; human taste chooses the winner. Push exactly that manifest entry, by stable ID or 1-based index:

pattern-gen push --manifest ./ideas/manifest.json --idea <index-or-id> \
  --name "Chosen treatment" --with-preview --json

Balanced sampling and a built-in gallery are intentionally out of scope. For a release proof, pnpm pack:proof:typography -- --proof-dir <new-local-posix-dir> packs @takazudo/pgen, installs it into a fresh consumer, runs the full count-100 fixture twice with the exact same inputs, compares all 100 idea records and artifacts, and retains proof-report.json. Local POSIX temporary storage is the reliable generation boundary. To copy the first verified bundle onto a mounted or synced volume, add --copy-to <new-destination>; the command compares every file hash after copying.

To exercise the installed CLI's output transaction directly on a mounted or synced filesystem, add --direct-out <new-destination> to either the bounded or full proof. This separate smoke writes two ideas straight to that destination through pattern-gen ideas --out-dir, then validates its manifest, every config and PNG hash, exact Square/Wide dimensions, and the absence of an incomplete reservation marker. The proof report records this direct run separately. Every destination must be explicit and must not already exist:

# Bounded CI-sized proof plus direct mounted-output transaction.
pnpm pack:smoke -- --direct-out <new-mounted-destination>

# Retained 100×2 local proof plus the same bounded direct-output transaction.
pnpm pack:proof:typography -- --proof-dir <new-local-posix-dir> \
  --direct-out <new-mounted-destination>

The default temporary proof tree is cleaned automatically. Explicit --proof-dir, --direct-out, and --copy-to destinations remain caller-owned so evidence can be inspected before removing those exact paths.

License

MIT — see LICENSE.