m/ImaGen

Files

mAi 2a8bd4313b mAi: #5 - tmux-window preview for generate

Adds an optional `imagen generate` post-step that opens a sibling
tmux window running tmux-img --hold <path>.

- internal/preview: Mode (auto|on|off), Resolve, and a Spawner that
  shells out to tmux new-window. Typed errors for missing tmux,
  missing tmux-img, and "preview forced on outside $TMUX".
- cmd/imagen/generate: --preview / --no-preview flags plus
  $IMAGEN_PREVIEW. Resolution chain: config -> env -> flag.
  auto requires both stdout-is-tty and $TMUX. Failures are
  warnings - the image is already on disk.
- internal/config: output.preview field, validated to auto|on|off,
  threaded into the sample.
- Tests for ParseMode, Resolve, Spawn argv (incl. shell quoting of
  paths with apostrophes), missing-binary errors, and the CLI
  resolution table.
- Docs (usage + architecture) updated.

/imagine SKILL.md edit lives in dotfiles - deferred to coordinate
with #4.

2026-05-08 17:09:59 +02:00

4.0 KiB

Raw Blame History

Using imagen

Subcommands

imagen generate <prompt> [flags]    generate one image
imagen backends                     list configured + registered backends
imagen config init                  print a sample imagen.yaml on stdout
imagen config validate              parse + validate the active config
imagen config path                  print the resolved config path
imagen serve [--addr :8080]         (stub) start the HTTP server
imagen version                      print version

`generate` flags

Flag	Default	Notes
`--backend`	`default_backend` from config	Instance name from `imagen.yaml`
`--size`	`1024x1024`	`WxH`
`--seed`	`0` (= backend default)
`--steps`	`0` (= backend default)
`--style`	empty	One of `imagen config init`'s style names
`--negative`	empty	Negative prompt (ignored by some adapters)
`--output`	empty (= use naming template)	Explicit path
`--no-sidecar`	`false`	Skip the JSON sidecar even if config enables it
`--preview`	(auto)	Force open a tmux preview window via `tmux-img`
`--no-preview`	(auto)	Suppress the preview window (use for batch / CI callers)
`--config`	`~/.config/imagen.yaml`	Override config path

Preview window

After a successful generate, imagen optionally opens a sibling tmux window named img:<slug> running tmux-img --hold <path>. The new window is spawned in the background (tmux new-window -d) so the generating pane keeps focus and its terminal output.

Resolution order is config → $IMAGEN_PREVIEW → flag (later wins):

output.preview in imagen.yaml: auto (default) | on | off
IMAGEN_PREVIEW=auto|on|off overrides config
--preview / --no-preview override env

auto previews iff stdout is a TTY and $TMUX is set. on previews unconditionally and errors outside a tmux session. off never previews.

Preview failures are non-fatal — the image already wrote.

Examples

# Quick smoke test — mock backend ships in-tree
imagen generate "test" --backend mock --output /tmp/x.png

# Real generation, FLUX-schnell on mRock via ComfyUI
imagen generate "a wide editorial blog header about RAG systems" \
  --backend flux-schnell-local \
  --style blog-header \
  --size 1536x768

# Explicit seed for reproducibility
imagen generate "a cat in a fishbowl" --backend mock --seed 42 --output /tmp/cat.png

Config

A complete sample is in imagen config init. Adapters get only their own sub-block — see ../CLAUDE.md for the contract.

Naming template

output.naming placeholders:

Placeholder	Replaced with
`{date}`	`2026-05-08`
`{time}`	`143015` (no separators)
`{slug}`	lowercased ASCII prompt, ≤ 40 chars
`{seed}`	seed actually used
`{backend}`	backend instance name
`{ext}`	file extension matching `Result.MimeType`

Unknown placeholders are left literal.

Credentials

API-backed adapters read tokens from env vars referenced by the config (api_token_env, api_key_env). Never put a token in imagen.yaml.

export REPLICATE_API_TOKEN=...
imagen generate "a cat" --backend flux-dev-replicate

4.0 KiB Raw Blame History