lcode-cli 0.40.0__tar.gz → 0.42.0__tar.gz

{lcode_cli-0.40.0 → lcode_cli-0.42.0}/CHANGELOG.md

@@ -6,6 +6,42 @@ All notable changes to lcode are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.42.0] - 2026-10-24
+
+### Added
+
+- **Image mode's options, results and follow-ups** (#151). See
+  [Image mode](https://nasser1941.github.io/lcode/modes/#image-mode).
+  - **Options in a request** (`a red fox --n 4 --ar 16:9 --seed 42 --quality best --style photo`)
+    or for the session (`/options n=4 ar=16:9`): how many images, the shape, the seed (counting up
+    over several images), a quality preset (0.5, 1 or 2 megapixels), ten style presets, and a
+    negative prompt for models that use one.
+  - **Numbered results, shown in the terminal:** the picture itself in kitty, Ghostty, iTerm2 and
+    WezTerm, and a half-block colour preview elsewhere (the `preview` setting).
+  - **Follow-ups:** `/again` (new seeds), `/vary 3` (four variations of image #3), `/gallery` and
+    `/open 3`. The gallery and options are saved with the session.
+  - `lcode --mode image -p "… --n 2"` reports every image's file and seed.
+  - One image is now named `<time>-<prompt>.png` (no `-1`).
+
+## [0.41.0] - 2026-10-23
+
+### Added
+
+- **Image models to choose from, installed by lcode** (#150). lcode's media catalog lists the image
+  models it can run, with their size, license, measured speed and whether they fit your GPU.
+  **Z-Image Turbo** (photorealistic) joins FLUX.2 klein 4B (fast): 17 s and 3.5 s per 1024×1024
+  image on a 12 GB laptop GPU. See
+  [Image models](https://nasser1941.github.io/lcode/modes/#image-models).
+  - **Choose one:** `/models` in image mode (numbered) or `/model z-image-turbo` switches; the
+    `image_model` setting is the default, and sessions keep theirs.
+  - **Installed on demand:** a model that isn't installed downloads with your next image, after you
+    say yes, or ahead with `lcode media install <model>`. lcode downloads only the missing files
+    (models share text encoders and VAEs) into ComfyUI's model folders, checks the disk first,
+    verifies each file's SHA-256, and resumes interrupted downloads. `HF_TOKEN` works for gated
+    models.
+  - **`lcode media`** lists image and video models with what fits and what's installed, and
+    `lcode doctor` says how to install the image model when it's missing.
+
 ## [0.40.0] - 2026-10-23
 
 ### Added
@@ -904,7 +940,9 @@ First public release.
 - `AGENTS.md` project instructions and `/init` to generate them.
 - One-line installer for Linux and macOS.
 
-[Unreleased]: https://github.com/nasser1941/lcode/compare/v0.40.0...HEAD
+[Unreleased]: https://github.com/nasser1941/lcode/compare/v0.42.0...HEAD
+[0.42.0]: https://github.com/nasser1941/lcode/compare/v0.41.0...v0.42.0
+[0.41.0]: https://github.com/nasser1941/lcode/compare/v0.40.0...v0.41.0
 [0.40.0]: https://github.com/nasser1941/lcode/compare/v0.39.0...v0.40.0
 [0.39.0]: https://github.com/nasser1941/lcode/compare/v0.38.0...v0.39.0
 [0.38.0]: https://github.com/nasser1941/lcode/compare/v0.37.0...v0.38.0

{lcode_cli-0.40.0 → lcode_cli-0.42.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: lcode-cli
-Version: 0.40.0
+Version: 0.42.0
 Summary: A local-first terminal coding agent powered by open-weight models on your own GPU or Mac, via Ollama.
 Project-URL: Homepage, https://nasser1941.github.io/lcode/
 Project-URL: Documentation, https://nasser1941.github.io/lcode/

{lcode_cli-0.40.0 → lcode_cli-0.42.0}/docs/configuration.md

@@ -27,6 +27,8 @@ lcode config path                      # print the file location
 | `comfyui_url` | `http://127.0.0.1:8188` | ComfyUI's address, for image and video mode |
 | `comfyui_path` | (found) | Your ComfyUI folder, if lcode doesn't find it; lcode starts it when needed ([ComfyUI](modes.md#comfyui)) |
 | `media_dir` | `.lcode/media` | Where images and videos go: a folder in the project, or an absolute path |
+| `preview` | `auto` | Images in the terminal: `auto`, `kitty`, `iterm`, `blocks` (colour text) or `off` ([results](modes.md#results)) |
+| `image_model` | `flux2-klein-4b` | The model image mode uses: a key from `lcode media` ([image models](modes.md#image-models)) |
 | `think` | `true` | Let the model reason before answering |
 | `web` | `on` | Web search and page fetching: `on`, `ask` (before each search/website) or `off` |
 | `search_backend` | `auto` | `auto`, `ollama`, `brave`, `tavily` or `searxng`; `auto` uses the first one configured |

lcode_cli-0.42.0/docs/modes.md

@@ -0,0 +1,211 @@
+# Modes: code, image and video
+
+lcode makes three kinds of things, each in its own mode with its own models:
+
+| Mode | What it makes | The model doing the work |
+|---|---|---|
+| **code** (default) | Code: it reads, writes, runs and checks your project | A coding language model in Ollama (or another server) |
+| **image** | Images from a description and reference images | An image model, run by ComfyUI on your GPU |
+| **video** | Videos from a description, a start image or references | A video model, run by ComfyUI on your GPU |
+
+```text
+❯ /mode image
+Mode: image (local image generation).
+Unloaded qwen3.6-35b to free the GPU for images.
+Starting ComfyUI (~/comfy/ComfyUI) in the background.
+Describe an image and press Enter: FLUX.2 klein 4B makes it on your GPU, into .lcode/media.
+image ❯ a red fox sitting in fresh snow at dusk
+◆ #1 .lcode/media/20261023-184531-a-red-fox-sitting-in-fresh-snow-at-dusk.png  1024×1024 · FLUX.2 klein 4B · seed 3714779554 · 8.0 s
+```
+
+- **Switching:** `/mode code`, `/mode image` and `/mode video` switch in a session. `lcode --mode image`
+  starts in one, and `lcode config set mode video` makes it the default. `/mode` alone shows
+  the current one.
+- **Where it shows:** the banner, the status bar and the prompt (`image ❯`) show the mode.
+- **Sessions:** a session keeps the mode it was made in, and resuming it brings that mode back.
+
+## Code mode makes code only
+
+Code mode is the coding agent, as before, and it no longer generates images or videos. The MCP
+servers that did (`comfyui` and `xai`) are gone from the MCP catalog, and lcode doesn't load them
+in code mode even if they're still in your `mcp.json`. It says so once.
+
+## Image mode
+
+In image mode, what you type is a description, and lcode makes the picture. No language model is
+involved: lcode fills in its own ComfyUI workflow for the image model and follows the job itself,
+with the image model you choose (see [Image models](#image-models)).
+
+```text
+image ❯ a red fox in fresh snow --n 2 --ar 16:9 --seed 7
+◆ #1 .lcode/media/20261023-194019-a-red-fox-in-fresh-snow.png  1360×768 · FLUX.2 klein 4B · seed 7 · 4.9 s
+▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀   (the picture, in colour)
+◆ #2 .lcode/media/20261023-194024-a-red-fox-in-fresh-snow.png  1360×768 · FLUX.2 klein 4B · seed 8 · 2.7 s
+image ❯ /vary 1 --n 2
+Variations of #1: a red fox in fresh snow
+◆ #3 …
+```
+
+### Options
+
+Add them to a request, or set them for the session with `/options` (`/options n=4 ar=16:9
+quality=best style=photo`). A flag in a request wins over `/options` for that request. `/options`
+alone shows them.
+
+| Flag | `/options` | What it does |
+|---|---|---|
+| `--n 4` | `n=4` | How many images: 1 to 8. Each gets its own seed. |
+| `--ar 16:9` | `ar=16:9` | The shape: a ratio (`3:2`, `9:16`, up to 4:1), a name (`square`, `portrait`, `landscape`, `wide`, `tall`, `photo`, `cinema`), or pixels (`--size 1344x768`). |
+| `--seed 42` | `seed=42` | The same seed and settings make the same image. With `--n`, the seeds count up (42, 43, …). `seed=random` goes back to a new one each time. |
+| `--quality best` | `quality=best` | `fast` (about 0.5 megapixels, fewer steps for models that allow it), `balanced` (1 megapixel, the default), `best` (2 megapixels, more steps where they help). |
+| `--style photo` | `style=photo` | Adds a style to the description: `photo`, `cinematic`, `anime`, `watercolor`, `oil`, `pixel`, `3d`, `sketch`, `comic`, `flat`. `style=none` takes it off. |
+| `--no "text, people"` | `no="text"` | A negative prompt, for models that use one. FLUX.2 klein and Z-Image Turbo don't (they're distilled), and lcode says so: describe what you want instead. |
+
+### Results
+
+- **Numbered:** every image in the session gets a number (`#3`), shown with its file, size, model,
+  seed and time.
+- **Shown in the terminal:** in kitty, Ghostty, iTerm2 and WezTerm the picture itself appears
+  under its line. Other terminals get a small colour preview drawn with half blocks. The
+  `preview` setting chooses: `auto`, `kitty`, `iterm`, `blocks` or `off`. Inside tmux or screen,
+  lcode draws the half-block preview.
+- **Follow-ups:**
+
+| Command | What it does |
+|---|---|
+| `/again` | The last request again with new seeds; flags change it (`/again --n 4 --ar 9:16`) |
+| `/vary 3` | Four variations of image #3: its prompt and options, new seeds (`/vary 3 --n 2`; the last image without a number) |
+| `/gallery` | The session's images with their prompt, size, model and seed; `/gallery all` lists the latest 50 in the media folder |
+| `/open 3` | Opens image #3 in your image viewer (the last one without a number) |
+
+- **Sessions:** the gallery and `/options` are saved with the session, so `lcode -c` or `/resume`
+  brings them back. An image session is listed under its first prompt.
+
+- **Progress:** the status line says what ComfyUI is doing (loading the model, reading the
+  prompt, drawing, decoding), the step, the time left and the time so far. If other jobs are ahead
+  in ComfyUI's queue, it says how many.
+- **Cancel** with Esc or Ctrl+C: lcode cancels the job in ComfyUI too, so it stops using the GPU.
+- **Type ahead:** what you type while an image is being made waits in the next prompt.
+- **Files:** each image goes to `.lcode/media/` in the project (the `media_dir` setting), named
+  after the time and the prompt, with a `.json` next to it holding the prompt, model, seed, size,
+  steps, quality and style. PNGs carry the same in their own metadata (an `lcode` text chunk), and ComfyUI's workflow
+  as well. `.lcode/media/` keeps itself out of git; a folder of your own (`lcode config set
+  media_dir assets/generated`) doesn't.
+- **Nothing is lost:** lcode writes each job down while it runs. If lcode crashes or the terminal
+  closes before an image arrives, the next request in image mode saves it.
+- **From scripts:** `lcode --mode image -p "a red fox in the snow --n 2"` makes the images and
+  exits; with `--output json` it prints a result with the file paths, the model, the seeds, the size
+  and the time.
+- **No Ollama needed:** `lcode --mode image` starts even when Ollama isn't running or the coding
+  model isn't installed; `/mode code` then says what's missing.
+
+## ComfyUI
+
+ComfyUI runs the image and video models; lcode drives it through its API.
+
+- **One that's running** at `comfyui_url` (by default `http://127.0.0.1:8188`) is used as it is.
+- **Otherwise lcode starts one** in the background when you switch to image mode, so the first
+  image waits less, and stops it when you quit or go back to code mode, or when the terminal
+  closes. It looks in the `comfyui_path` setting, then the folder the `comfy` CLI uses, then
+  `~/comfy/ComfyUI`, `~/ComfyUI`, `~/comfyui` and `~/Documents/ComfyUI`. It uses that install's
+  own Python (its `.venv` or `venv`), and logs to `comfyui.log` in lcode's state folder.
+- **With none,** your first image request offers to install ComfyUI into lcode's state folder with
+  [comfy-cli](https://github.com/Comfy-Org/comfy-cli) and the PyTorch build for your GPU (NVIDIA,
+  Apple Silicon or CPU). That downloads several GB. To install it yourself:
+
+  ```bash
+  uvx --from comfy-cli comfy install
+  ```
+
+- **`lcode doctor`** shows whether ComfyUI is running or found, and whether the image model is
+  installed.
+
+## Image models
+
+lcode's media catalog lists the image models it can run, with what each needs and whether it fits
+your machine. `/models` in image mode shows them, numbered; pick one with its number, or `/model
+z-image-turbo`. `lcode config set image_model z-image-turbo` makes one the default.
+
+```text
+image ❯ /models
+  1. ● FLUX.2 klein 4B (flux2-klein-4b)  text-to-image · 12.4 GB · installed · fits (~9 GB of 12 GB GPU memory)
+        1024×1024: 3.5 s per image, 14 s for the first with ComfyUI starting (RTX 4080 Laptop, 12 GB)
+  2.   Z-Image Turbo (z-image-turbo)  text-to-image · 14.6 GB · 6.5 GB to download · fits (~9 GB of 12 GB GPU memory)
+        1024×1024: 17 s per image (1.9 s per step), 23 s for the first (RTX 4080 Laptop, 12 GB)
+  Switch to which model? (number or name, Enter to keep FLUX.2 klein 4B): 2
+Image model: Z-Image Turbo.
+Not installed yet: 6.5 GB download with your next image (you're asked first).
+```
+
+| Model | Made by | License | Steps | Good at |
+|---|---|---|---|---|
+| **FLUX.2 klein 4B** (default) | Black Forest Labs | Apache 2.0 | 4 | Speed: a few seconds per image |
+| **Z-Image Turbo** | Tongyi-MAI (Alibaba) | Apache 2.0 | 8 | Photorealism, text in images; slower |
+
+Measured speeds are in the list (`/models`, `lcode media`) and in [Measured](#measured).
+
+- **Installing:** a model that isn't installed downloads with your next image, after you say yes.
+  You can also install it ahead with `lcode media install z-image-turbo`. lcode downloads only
+  the files ComfyUI doesn't have: models share text encoders and VAEs, so Z-Image Turbo needs
+  6.5 GB once FLUX.2 klein is there. Files go into ComfyUI's model folders, and the folders of
+  `extra_model_paths.yaml` count when ComfyUI is running.
+- **Safe downloads:** lcode checks the disk first and keeps 2 GB free. The progress shows the
+  speed and the time left. Each file is checked against Hugging Face's SHA-256 before it's used.
+- **Interrupted?** Ctrl+C pauses a download, and so does a dropped connection. Run the same install
+  again and it continues where it stopped (a `.part` file holds what arrived).
+- **Gated models:** for a model whose license you must accept on Hugging Face, accept it there
+  and set `HF_TOKEN`. lcode sends the token to huggingface.co only.
+- **Will it fit?** On NVIDIA GPUs the list compares an estimate of the GPU memory the model needs
+  with your GPU: the largest of its files plus 1.5 GB. ComfyUI loads the text encoder, the model and
+  the VAE one after another, so the largest file sets the need. A model too big for the GPU still
+  runs, slower, because ComfyUI keeps part of it in RAM. On Apple Silicon, the list compares it
+  with unified memory.
+
+```bash
+lcode media                        # image and video models, what fits, what's installed
+lcode media install z-image-turbo  # download what's missing (asks first; --yes doesn't)
+```
+
+### Measured
+
+On an RTX 4080 Laptop GPU (12 GB), FLUX.2 klein 4B makes a 1360×768 image in 2.6 to 2.8 s and a
+`--quality fast` image (720×720) in 1.3 to 2.0 s once it's loaded.
+
+
+On an RTX 4080 Laptop GPU (12 GB) with 32 GB of RAM, ComfyUI 0.38, 1024×1024, four different
+prompts each:
+
+| Model | First image (ComfyUI starting, model loading) | Each next image | Per step |
+|---|---|---|---|
+| FLUX.2 klein 4B (fp8) | 14.3 s | 3.5 s | 0.6 s (4 steps) |
+| Z-Image Turbo (int8) | 22.9 s | 17.4 s | 1.9 s (8 steps) |
+
+ComfyUI uses whatever GPU memory is free to keep models loaded (11.3 to 11.5 GB here), so the
+memory a model *needs* is lower than what `nvidia-smi` shows while it runs.
+
+## One model on the GPU at a time
+
+Image and video modes don't need the big coding model: the image or video model does the work. A
+small optional model will help with prompts later. Image and video models need the GPU to
+themselves:
+
+- **Into image or video mode:** lcode unloads its coding model from Ollama, and checks again
+  before each image.
+- **Back to code mode:** lcode stops the ComfyUI it started, or asks yours to free its memory,
+  then loads the coding model again in the background.
+
+## Coming next
+
+Video mode doesn't generate yet: a request there says what's coming instead of going anywhere.
+
+- **#150 Media model catalog** (image models done; video models come with video generation).
+- **#151, #152 Image mode:** generating, variations, sizes and seeds, a gallery, editing,
+  references, inpainting, upscaling.
+- **#153, #154 Video mode:** from text or a start image, first and last frames, several
+  references, camera moves, longer clips, sound.
+- **#155 Movies:** storyboards with a consistent cast, shots stitched into one film.
+- **#156 Prompt assistant:** a small local model for prompts and follow-ups.
+- **#157 Cloud generation**, with costs shown (Grok Imagine first).
+
+The permission mode (`ask`, `plan`, `auto-edit`, `yolo`) is a different setting: `/permissions`
+sets it, and Shift+Tab cycles it as before.

{lcode_cli-0.40.0 → lcode_cli-0.42.0}/docs/quickstart.md

@@ -12,7 +12,7 @@ lcode
 
 ```text
 ╭──────────────────────────────────────────────╮
-│ lcode v0.40.0 — local coding agent           │
+│ lcode v0.42.0 — local coding agent           │
 │                                              │
 │ model    lcode-qwen3.6-35b                   │
 │ context  256K tokens                         │

{lcode_cli-0.40.0 → lcode_cli-0.42.0}/docs/usage.md

@@ -7,6 +7,7 @@ lcode [options]              # interactive session in the current directory
 lcode setup [model]          # pick, download and configure a model
 lcode models                 # the model catalog and what fits this machine
 lcode doctor                 # check the installation (include this in bug reports)
+lcode media [install MODEL]  # image and video models: what fits here, what's installed; install one
 lcode config [set|unset]     # show or change settings
 lcode bench [models]         # score models on small coding tasks on this machine
 lcode mcp [catalog|add|list] # connect MCP servers: Jira, GitHub, AWS, databases… (see MCP servers)
@@ -80,6 +81,7 @@ reasoning is on.
 | `/think [on\|off]` | Toggle reasoning |
 | `/verbose` | Toggle showing the reasoning text |
 | `/mode [code\|image\|video]` | Switch what lcode makes: [code, images or videos](modes.md) |
+| `/options`, `/again`, `/vary N`, `/gallery`, `/open N` | Image mode: [options for the session, follow-ups on results](modes.md#results) |
 | `/permissions [ask\|plan\|auto-edit\|yolo]` | Set the permission mode |
 | `/cd DIR` | Change the working directory |
 | `/todos` | Show the model's task list |

{lcode_cli-0.40.0 → lcode_cli-0.42.0}/src/lcode/__init__.py

@@ -3,7 +3,7 @@
 From a program: `from lcode import Session` (see lcode.api).
 """
 
-__version__ = "0.40.0"
+__version__ = "0.42.0"
 
 API = ("Session", "Result", "Options", "SetupError")
 

{lcode_cli-0.40.0 → lcode_cli-0.42.0}/src/lcode/agent.py

@@ -308,6 +308,8 @@ class Settings:
     comfyui_url: str = "http://127.0.0.1:8188"
     comfyui_path: str | None = None  # a ComfyUI install lcode doesn't find by itself (lcode.comfy)
     media_dir: str = ".lcode/media"  # where image and video mode save their files (lcode.media)
+    image_model: str = "flux2-klein-4b"  # the media catalog's model image mode uses (lcode.media_catalog)
+    preview: str = "auto"  # images in the terminal: auto, kitty, iterm, blocks or off (lcode.preview)
     num_batch: int | None = None
     keep_alive: str = "30m"
     think: bool = True
@@ -374,6 +376,11 @@ class Agent:
         self.interactive = True  # False for `lcode -p`: no end-of-session questions
         self.comfy_process = None  # the ComfyUI lcode started for image and video mode, stopped when it exits
         self.no_coding_model = ""  # why there's no coding model, when lcode started in image or video mode without
+        from lcode.imageopts import Options as ImageOptions
+
+        self.image_options = ImageOptions()  # image mode's defaults for this session (/options)
+        self.media_results: list[dict] = []  # the session's images, numbered (/gallery, /vary, /open)
+        self.last_request: tuple[str, ImageOptions] | None = None  # for /again
         self.reflected = 0  # messages before this index were already checked for notes to remember
         self._memory: memory_notes.Memory | None = None
         self._agent_types: tuple[Path, dict[str, subagents.AgentType], list[str]] | None = None
@@ -678,8 +685,10 @@ class Agent:
         return any(m.get("role") == "user" for m in self.messages)
 
     def save(self) -> None:
-        if not (self.has_conversation() or self.session_name):
+        if not (self.has_conversation() or self.session_name or self.media_results):
             return  # nothing worth resuming
+        if not self.session_title and not self.has_conversation() and self.media_results:
+            self.session_title = " ".join(self.media_results[0]["prompt"].split())[:60]  # an image session
         self.session_title = self.session_title or sessions.title_from(self.messages)
         f = self.session_file()
         f.parent.mkdir(parents=True, exist_ok=True)
@@ -687,6 +696,8 @@ class Agent:
             "cwd": str(self.workspace),  # where `lcode -c` there finds it, wherever the shell moved
             "model": self.settings.model,
             "mode": self.settings.mode,
+            "image_model": self.settings.image_model,
+            "media": {"results": self.media_results, "options": self.image_options.to_json()},
             "name": self.session_name,
             "title": self.session_title,
             "messages": self.messages,
@@ -735,6 +746,11 @@ class Agent:
         self.session_name = data.get("name", "")
         if data.get("mode") in ("code", "image", "video"):
             self.settings.mode = data["mode"]  # a session belongs to the mode it was made in
+        if isinstance(data.get("image_model"), str):
+            self.settings.image_model = data["image_model"]
+        media = data.get("media") or {}
+        self.media_results = [r for r in media.get("results") or [] if isinstance(r, dict) and "path" in r]
+        self.image_options = type(self.image_options).from_json(media.get("options") or {})
         self.session_title = data.get("title") or sessions.title_from(self.messages)
         self.tools.read_mtimes.clear()  # files may have changed since; the model must read them again
         self.tools.todos = list(data.get("todos") or [])

{lcode_cli-0.40.0 → lcode_cli-0.42.0}/src/lcode/api.py

@@ -200,6 +200,8 @@ def open_agent(cwd: Path, options: Options, console: Console, hw: Hardware | Non
         comfyui_url=cfg["comfyui_url"],
         comfyui_path=cfg["comfyui_path"],
         media_dir=cfg["media_dir"],
+        image_model=cfg["image_model"],
+        preview=cfg["preview"],
         web=switch(options.web, cfg["web"], "on"),
         search_backend=cfg["search_backend"],
         searxng_url=cfg["searxng_url"],

{lcode_cli-0.40.0 → lcode_cli-0.42.0}/src/lcode/cli.py

@@ -777,9 +777,10 @@ def exit_on_hangup() -> None:
 
 def comfyui_status(cfg: dict) -> tuple[str, bool | None]:
     """lcode doctor's ComfyUI line: running or found, and whether the image model is there."""
-    from lcode import comfy, media
+    from lcode import comfy
+    from lcode import media_catalog as catalog
 
-    workflow = comfy.load_workflow(media.IMAGE_WORKFLOW)
+    model = catalog.load().find(cfg.get("image_model") or "") or catalog.load().models[catalog.DEFAULT_IMAGE]
     server = comfy.Server(cfg["comfyui_url"])
     stats = server.stats()
     install = None if stats else comfy.find_install(cfg["comfyui_path"])
@@ -787,14 +788,13 @@ def comfyui_status(cfg: dict) -> tuple[str, bool | None]:
         return "not found: image mode offers to install it (or lcode config set comfyui_path <folder>)", None
     if stats:
         where = f"{(stats.get('system') or {}).get('comfyui_version', '?')} running at {server.url}"
-        installed = {folder: set(server.models(folder)) for folder in workflow.models}
     else:
         where = f"{install.path} (lcode starts it in image mode)"
-        installed = {folder: set(comfy.local_models(install, folder)) for folder in workflow.models}
-    missing = [f"{f}/{names[0]}" for f, names in workflow.models.items() if not installed[f] & set(names)]
+    _, missing = catalog.chosen_files(model, catalog.lister(server if stats else None, install))
     if missing:
-        return f"{where} · {workflow.name} not installed (missing {', '.join(missing)})", None
-    return f"{where} · image model: {workflow.name}", True
+        size = sum(f.gb for f in missing)
+        return f"{where} · {model.name} not installed: lcode media install {model.key} ({size:.1f} GB)", None
+    return f"{where} · image model: {model.name}", True
 
 
 def media_request(agent, prompt: str, out: Console, quiet: bool) -> None:
@@ -812,7 +812,7 @@ def media_request(agent, prompt: str, out: Console, quiet: bool) -> None:
         api.close_agent(agent)
         sys.exit(2)
     try:
-        made = media.generate_image(agent, prompt)
+        made = media.request(agent, prompt)
     except (media.MediaError, KeyboardInterrupt) as e:
         message = str(e) or "Cancelled."
         if quiet:
@@ -826,12 +826,13 @@ def media_request(agent, prompt: str, out: Console, quiet: bool) -> None:
             "type": "result",
             "status": "success",
             "mode": "image",
-            "files": [str(path) for path in made.files],
-            "model": made.model,
-            "seed": made.seed,
-            "width": made.width,
-            "height": made.height,
-            "seconds": round(made.seconds, 1),
+            "files": [str(path) for one in made for path in one.files],
+            "model": made[0].model,
+            "seed": made[0].seed,
+            "seeds": [one.seed for one in made],
+            "width": made[0].width,
+            "height": made[0].height,
+            "seconds": round(sum(one.seconds for one in made), 1),
         }
         print(json.dumps(result, ensure_ascii=False), flush=True)
     api.close_agent(agent)
@@ -909,6 +910,13 @@ def build_subparsers() -> dict[str, argparse.ArgumentParser]:
     subs["setup"] = p
     subs["models"] = argparse.ArgumentParser(prog="lcode models", description="List models and how they fit here.")
     subs["doctor"] = argparse.ArgumentParser(prog="lcode doctor", description="Check the installation.")
+    p = argparse.ArgumentParser(
+        prog="lcode media", description="Image and video models: list them, with how they fit here, or install one."
+    )
+    p.add_argument("action", nargs="?", choices=["list", "install"], default="list")
+    p.add_argument("model", nargs="?", help="with install: a model key from the list, e.g. z-image-turbo")
+    p.add_argument("-y", "--yes", action="store_true", help="don't ask before downloading")
+    subs["media"] = p
     p = argparse.ArgumentParser(prog="lcode config", description="Show or change settings.")
     p.add_argument("action", nargs="?", choices=["show", "set", "unset", "path"], default="show")
     p.add_argument("key", nargs="?", choices=list(config.SETTINGS))
@@ -1065,6 +1073,55 @@ def cmd_index(args) -> None:
     )
 
 
+def cmd_media(args) -> None:
+    """lcode media [list] | install <model>: the media catalog, what's installed in ComfyUI, downloads."""
+    from rich.prompt import Confirm
+
+    from lcode import comfy, media
+    from lcode import media_catalog as catalog
+
+    try:
+        cfg = config.load()
+    except ConfigError as e:
+        fail(str(e))
+    cat, hw = catalog.load(), detect()
+    server = comfy.Server(cfg["comfyui_url"])
+    install = comfy.find_install(cfg["comfyui_path"])
+    running = server.stats() is not None
+    installed = catalog.lister(server if running else None, install) if running or install else None
+    if args.action == "install":
+        model = cat.find(args.model or "")
+        if model is None:
+            fail(f"no media model {args.model!r}: lcode media lists them")
+        if not running and install is None:
+            fail(f"lcode needs ComfyUI to install models into. {comfy.install_hint()}")
+        ask = None if args.yes else (lambda q: Confirm.ask(q, default=True, console=console))
+        try:
+            saved = catalog.install(model, server if running else None, install, console, ask)
+        except catalog.CatalogError as e:
+            fail(str(e))
+        how = f" ({len(saved)} file(s) downloaded)." if saved else "."
+        console.print(f"[green]{model.name} is installed[/]{how}")
+        return
+    where = (
+        f"ComfyUI at {server.url}" if running else (f"{install.path} (not running)" if install else "no ComfyUI found")
+    )
+    console.print(f"[dim]{hw.describe()} · {where} · image model: {cfg['image_model']}[/]\n")
+    for mode in ("image", "video"):
+        models = cat.for_mode(mode)
+        console.print(f"[bold]{mode.capitalize()} models[/]")
+        if not models:
+            console.print(f"  [dim]{media.SOON[mode]}[/]\n")
+            continue
+        for m in models:
+            line = escape(catalog.describe(m, hw, installed))
+            console.print(f"  [bold]{m.key:<16}[/] {escape(m.name)} [dim]· {line}[/]")
+            if m.measured:
+                console.print(f"  {'':<16} [dim]{escape(m.measured)}[/]")
+        console.print()
+    console.print("[dim]Install one: lcode media install <model> · choose in image mode: /model <model>[/]")
+
+
 def cmd_mcp(args) -> None:
     from lcode.mcp.commands import run
 
@@ -1075,6 +1132,7 @@ COMMANDS = {
     "setup": cmd_setup,
     "models": cmd_models,
     "doctor": cmd_doctor,
+    "media": cmd_media,
     "config": cmd_config,
     "bench": cmd_bench,
     "mcp": cmd_mcp,

{lcode_cli-0.40.0 → lcode_cli-0.42.0}/src/lcode/comfy.py

@@ -254,6 +254,14 @@ class Server:
         except (requests.RequestException, ValueError):
             return []
 
+    def folder_paths(self) -> dict[str, list[str]]:
+        """Where ComfyUI keeps each kind of model (its own folders and extra_model_paths.yaml's)."""
+        try:
+            r = requests.get(self.url + "/internal/folder_paths", timeout=10)
+            return r.json() if r.status_code == 200 else {}
+        except (requests.RequestException, ValueError):
+            return {}
+
     def upload(self, path: Path) -> str:
         """Upload an input image; the name to use in a workflow."""
         with path.open("rb") as f:
@@ -420,32 +428,18 @@ class Events:
 
 @dataclass
 class Workflow:
+    """A graph in ComfyUI's API format with `$name` placeholders: the model's files (by role, from media.toml),
+    the prompt, the seed and the settings in `defaults`."""
+
     key: str
-    name: str
-    task: str
-    models: dict[str, list[str]]  # ComfyUI folder -> file names it can use, preferred first
-    defaults: dict
     graph: dict
+    defaults: dict = field(default_factory=dict)
     labels: dict[str, str] = field(default_factory=dict)  # node id -> what it does, for progress
 
 
 def load_workflow(key: str) -> Workflow:
     data = json.loads(resources.files("lcode.workflows").joinpath(f"{key}.json").read_text())
-    return Workflow(key, data["name"], data["task"], data["models"], data.get("defaults", {}), data["graph"],
-                    data.get("labels", {}))  # fmt: skip
-
-
-def choose_files(server: Server, workflow: Workflow) -> tuple[dict[str, str], list[str]]:
-    """For each model the workflow needs, the installed file to use; and the folders where none is installed."""
-    chosen, missing = {}, []
-    for folder, names in workflow.models.items():
-        installed = set(server.models(folder))
-        found = next((n for n in names if n in installed), None)
-        if found:
-            chosen[folder] = found
-        else:
-            missing.append(f"{folder}/{names[0]}")
-    return chosen, missing
+    return Workflow(key, data["graph"], data.get("defaults", {}), data.get("labels", {}))
 
 
 PLACEHOLDER = re.compile(r"^\$([a-z_]+)$")
@@ -566,13 +560,15 @@ def describe_history_error(entry: dict) -> str:
 
 
 def save(server: Server, outputs: dict, folder: Path, stem: str, meta: dict) -> list[Path]:
-    """Fetch the job's files into `folder`: stem-1.png, … with stem-1.json next to each."""
+    """Fetch the job's files into `folder`: stem.png (stem-2.png if that's taken), or stem-1.png, … for several,
+    each with its settings in a .json next to it."""
     folder.mkdir(parents=True, exist_ok=True)
     items = [item for node in outputs.values() for kind in OUTPUT_KINDS for item in node.get(kind, [])]
+    items = [it for it in items if it.get("type", "output") == "output"]
     saved = []
-    for i, item in enumerate((it for it in items if it.get("type", "output") == "output"), 1):
+    for i, item in enumerate(items, 1):
         ext = Path(item["filename"]).suffix or ".png"
-        path = unique(folder / f"{stem}-{i}{ext}")
+        path = unique(folder / (f"{stem}{ext}" if len(items) == 1 else f"{stem}-{i}{ext}"))
         data = server.fetch(item)
         if ext.lower() == ".png":
             data = with_text(data, "lcode", json.dumps(meta, ensure_ascii=False))

{lcode_cli-0.40.0 → lcode_cli-0.42.0}/src/lcode/config.py

@@ -45,6 +45,8 @@ SETTINGS: dict[str, tuple[object, type, str]] = {
     "comfyui_url": ("http://127.0.0.1:8188", str, "ComfyUI, for image and video mode"),
     "comfyui_path": (None, str, "your ComfyUI folder, if lcode doesn't find it (lcode starts it when needed)"),
     "media_dir": (".lcode/media", str, "where images and videos go: a folder in the project, or an absolute path"),
+    "image_model": ("flux2-klein-4b", str, "the model image mode uses: a key from `lcode media`"),
+    "preview": ("auto", str, "images in the terminal: auto | kitty | iterm | blocks (colour text) | off"),
     "think": (True, bool, "let the model reason before answering (slower, better)"),
     "web": ("on", str, "web search and page fetching for the model: on | ask | off"),
     "search_backend": ("auto", str, "auto | ollama | brave | tavily | searxng (keys come from environment variables)"),
@@ -210,6 +212,17 @@ def coerce(key: str, value: object) -> object:
         raise ConfigError(f"permission_mode must be one of {', '.join(PERMISSION_MODES)}")
     if key == "mode" and value not in WORK_MODES:
         raise ConfigError(f"mode must be one of {', '.join(WORK_MODES)}")
+    if key == "preview":
+        from lcode.preview import PROTOCOLS
+
+        if value not in PROTOCOLS:
+            raise ConfigError(f"preview must be one of {', '.join(PROTOCOLS)}")
+    if key == "image_model":
+        from lcode import media_catalog
+
+        keys = [m.key for m in media_catalog.load().for_mode("image")]
+        if value not in keys:
+            raise ConfigError(f"image_model must be one of {', '.join(keys)} (see lcode media)")
     if typ is bool and isinstance(value, str):
         if value.lower() not in ("true", "false", "1", "0", "yes", "no", "on", "off"):
             raise ConfigError(f"{key} must be true or false")