Local GPU Imagegen

English | 简体中文

An MCP-first control plane with cryptographic model identity, explicit approvals, and durable run evidence for the ComfyUI setup you already use.

Run a supported ComfyUI workflow from Codex without modifying your setup.

uvx local-gpu-imagegen verify
uvx local-gpu-imagegen setup codex --apply

Setup stores a resolved, version-pinned launcher equivalent to uvx --from local-gpu-imagegen==0.9.1 local-gpu-imagegen serve; it does not depend on a console script from the temporary uvx environment. If an older entry reports client_setup_drift, remove only that client entry and apply setup again. Starting ComfyUI does not repair an MCP launcher failure; backend readiness is checked after the client loads the server.

Ask Codex:

Run this supported ComfyUI API workflow from Codex: <path>.
Use this prompt: <prompt>. Preserve every other workflow setting.

This path requires Python 3.11 or 3.12, Codex, an already-running local ComfyUI instance, an already-installed model, and one ordinary txt2img API workflow using the supported built-in topology. It uses your existing local image backend and model with no silent model downloads or switches. It does not install a backend, download a model, convert UI-format JSON, or execute a workflow that requires unsupported custom nodes. An explicit Windows portable managed-start option is documented below.

The v0.9 supported host scope is Windows 10/11 x64 with NVIDIA. The single py3-none-any wheel describes pure-Python packaging, not a separate Linux edition or a claim of Linux managed-generation support. Ubuntu CI verifies the platform-neutral MCP, packaging, existing-backend, and unsupported-platform contracts; Windows runs the complete portable-bootstrap suite.

ComfyUI generates the pixels. Local GPU Imagegen controls authority, reproducibility, review, and recovery around that generation.

Five-minute Quickstart | Launch playbook | Alternatives

Bring Your Own ComfyUI Workflow

The retained Codex workflow-onboarding session inspected and registered a supported graph, then bound its exact model components; it did not submit a prompt or use the GPU. Historical generated-image records remain available for technical audit, but v0.9 does not use them as promotional visuals or as evidence of image-quality superiority.

This path requires an existing local image backend and model; there are no silent model downloads or switches.

Guided Bootstrap (Windows NVIDIA)

For an existing environment, run bootstrap status and reuse only a verified portable root, checkpoint, and loopback endpoint. For a zero-environment setup, bootstrap plan shows the exact portable archive, checkpoint, byte ceiling, license URLs, SHA-256 hashes, disk/VRAM requirements, and bounded rollback; bootstrap apply requires the displayed explicit confirmation. Downloads are resumable and never silent. The frozen scope is Windows 10/11 x64 with NVIDIA RTX 20-series or newer, 10 GiB VRAM, and 30 GiB free disk. Docker is not required. This model-free bootstrap contract does not prove image generation or production readiness.

setup is read-only without --apply. The apply path delegates to the client's official mcp add command; Local GPU Imagegen does not edit client configuration files directly or download a model.

Trust proof: the retained ordinary-route result came from one installed Codex session. Discovery did not load weights; trust and route identity were explicit; successful rounds were bounded; review used the original-resolution PNG; finalization was bound to the reviewed bytes; and the run state remains recoverable. The evidence proves this one result, not complete 9+3 acceptance, measured performance, or production readiness.

v0.9 local acceptance: a fresh Windows/NVIDIA installation built from the user-approved ComfyUI archive and SDXL checkpoint reached managed readiness, served exactly seventeen MCP tools, and finalized one reviewed non-human environment image with byte-identical source and final hashes. The artifact remains local until a separate sanitized export and is not bundled in the package. Two separate character attempts failed strict hand, eye, or tail review; prominent-human anatomy quality is therefore not established.

Optional Managed ComfyUI Startup

Windows setup can register one existing portable root for managed startup:

uvx local-gpu-imagegen setup codex --apply `
  --auto-start-comfyui `
  --comfyui-root "<ComfyUI_windows_portable>"

The opt-in command validates the fixed portable layout and registers python_embeded\python.exe -s ComfyUI\main.py at 127.0.0.1:8188. It does not install ComfyUI or download a model. An already-running endpoint is reused but never owned or stopped. A child started by the MCP process is stopped at MCP exit only when its queue is empty; a non-empty queue is retained and reported. Both modes use the existing backend and model with no silent model downloads or switches. Workflow execution remains limited to supported built-in topologies; managed startup does not remove or manage custom nodes already present in the selected portable installation.

The animation is a deterministic simulated protocol demonstration, not model output or image-quality evidence. It remains secondary to the protocol and test evidence. Model-free tests cover the protocol and backend contracts, not image quality, broader named-client generation, performance, or complete 9+3 acceptance.

For Claude Code, use uvx local-gpu-imagegen setup claude-code --apply. Remove the entries with codex mcp remove local-gpu-imagegen or claude mcp remove --scope user local-gpu-imagegen. Use uvx local-gpu-imagegen doctor to inspect local backend readiness. The setup contracts and equivalent stdio launches are verified; one Codex installed-client generation is retained, while Claude Code generation remains pending. See Client compatibility.

DeepSeek Harness (DSH) connects through the same standard stdio MCP protocol with no setup command: register the server through dsh plugin --profile <name> add or point any MCP-compatible client at scripts/mcp_server.py. A real DSH-driven run completed the full discover_models (api_only) → recommend_models → start_run → get_run → generate_round sequence against a live ComfyUI checkpoint and produced a round-01.png artifact; initialize/tools/list/ping, verify_mcp.py, and verify_client_configs.py all pass.

Before PyPI publication, install the verified wheel or a source checkout, then use the equivalent local-gpu-imagegen verify and local-gpu-imagegen setup ... commands.

Why This Project

• Run supported workflows from your Agent: inspect and register ordinary ComfyUI API graphs instead of rebuilding them as one-off scripts.
• Reuse or explicitly manage your backend: ComfyUI is the primary existing-workflow path; an opt-in Windows portable supervisor removes manual startup without taking ownership of an existing process. AUTOMATIC1111/Forge and Diffusers remain compatibility paths.
• Make runs reproducible: freeze workflow, model identity, prompts, settings, seed, budget, and output hashes in a durable manifest.
• Use the installed CLI: verify readiness and delegate setup to the official Codex or Claude Code command without requiring a source checkout.
• Keep model authority explicit: discovery never loads weights, and generation cannot silently download or switch a model.
• Retain structured evidence: routes, budgets, attempts, image hashes, reviews, and recovery actions remain machine-readable and durable.
• Keep acceptance with the user: original-resolution review and later byte-bound finalization separate a generated image from an accepted final.
• Agent-guided workflow: a bundled Agent Skill turns a natural-language brief into a catalog-gated, confirmed run.
• Three delivery Profiles: standalone illustrations, presentation visuals, and UI visual assets share one deterministic run and review contract.
• Auditable hot revision: an immutable child run records a preserve/change contract and uses prompt refinement, img2img, or explicitly confirmed inpainting.
• Dependency-light MCP layer: protocol checks and tests use the Python standard library and require no GPU.
• Focused scope: image generation is kept separate from planning, memory, and unrelated agent features.

Experimental Composition Controls

The golden path uses ordinary sdxl-txt2img. The sdxl-regional-txt2img and sdxl-two-stage-copy-subject routes remain experimental, are not part of the golden path, and provide no fallback from the ordinary route. Their retained negative evidence does not establish a visual-quality improvement.

Image Quality Boundary

Model and workflow quality remain user supplied. Local GPU Imagegen adds explicit execution, review, recovery, and evidence; it does not modify diffusion algorithms or guarantee that a prompt workflow improves an image. Review now treats a change to the requested product medium, subject, practical use, or asset slot as semantic substitution and a failed constraint, even when the replacement looks cleaner.

See Image quality control and the frozen workflow no-regression gate. The retained gate ended in FAIL_WORKFLOW_REGRESSION; no public image-quality superiority claim is supported.

Source Checkout And Backend Setup

1. Verify The MCP Server

Python 3.11 or 3.12 is enough for this check. No GPU, model, or AI client is required.

python .\scripts\verify_mcp.py

Expected result:

{
  "ok": true,
  "transport": "stdio",
  "python": "<current-python>",
  "server": {"name": "local-gpu-imagegen", "version": "0.9.1"},
  "protocolVersion": "2024-11-05",
  "tools": [
    "local_gpu_branch_run",
    "local_gpu_cleanup_run",
    "local_gpu_confirm_mask",
    "local_gpu_discover_models",
    "local_gpu_finalize_run",
    "local_gpu_generate_image",
    "local_gpu_generate_round",
    "local_gpu_get_run",
    "local_gpu_imagegen_check",
    "local_gpu_list_profiles",
    "local_gpu_prepare_mask",
    "local_gpu_recommend_models",
    "local_gpu_record_review",
    "local_gpu_register_workflow",
    "local_gpu_set_model_trust",
    "local_gpu_start_run",
    "local_gpu_inspect_workflow"
  ]
}

2. Choose A Backend

Check current readiness:

python .\scripts\check_gpu.py

The command returns JSON. ready: false is a valid diagnostic state, not a protocol failure.

Managed startup is explicit and Windows-portable-only. It forces Python -s isolation so user-site Torch packages cannot contaminate the portable runtime, starts in the background so MCP initialization is not delayed, and lets the first managed readiness check wait up to the configured startup timeout. doctor itself remains read-only and never starts a backend.

To verify the MCP server under a specific virtual environment and call readiness through MCP:

python .\scripts\verify_mcp.py `
  --python .\.venv\Scripts\python.exe `
  --check-readiness

3. Connect An MCP Client

The bundled .mcp.json uses a relative command and cwd. For a client with global configuration, replace <project-root> with this clone's absolute path:

{
  "mcpServers": {
    "local-gpu-imagegen": {
      "command": "python",
      "args": ["<project-root>\\scripts\\mcp_server.py"]
    }
  }
}

Restart the client, then call local_gpu_imagegen_check before the first generation.

4. Ask For A Visual Asset

The bundled Agent Skill accepts ordinary requests. For example:

Create a 16:9 standalone anime character illustration with no generated text. Use up to two successful rounds, keep downloads disabled, and ask before changing the seed.

The Skill will not guess from a checkpoint filename or silently select a backend. It discovers current local inventory, applies user-local trust, recommends one exact route, and waits for confirmation without downloading a model.

Agent Skill Workflow

1. Call local_gpu_discover_models in api_only mode when inventory is unknown. Broader scans require a displayed plan and exact confirmation before filesystem access.
2. Use local_gpu_set_model_trust only after displaying one exact identity and receiving its exact trust confirmation. Private use and public evidence are separate scopes.
3. Call local_gpu_list_profiles for the intended authorization scope. Reuse known brief values and ask only for missing high-impact boundaries.
4. Call local_gpu_recommend_models. It returns one exact route and at most two alternatives without weakening hard requirements.
5. Display the exact resolved model_choice, backend, identity strength/hash or binding warning, workflow, compiler, dimensions, and budget. Wait for a new explicit confirmation after that display.
6. Start the frozen route -> read the persisted frozen run -> construct the complete generation plan -> spend at most the confirmed successful-round budget. Copy every route, identity, workflow, compiler, policy, and budget field from that run before adding prompts and parameters. A retained image consumes a round; a backend failure does not.
7. On a vision-capable host, display and inspect the original full-resolution image. Record the required anatomy, feet/contact, hands/objects, and text/watermark checks with the full rubric; a preview alone is insufficient. Failed or uncertain checks require refine or explore. A refine preserves the seed; an explore changes the seed.
8. When an eligible review returns quality status candidate, display its limitations, image SHA-256, and exact finalize:<run_id>:<round_number>:<image_sha256> value, then stop. Only a later user message containing that displayed value may authorize finalization; the Agent cannot accept its own candidate.
9. On a text-only host, retain exactly one successful round, mark review unavailable, report the unreviewed path, and stop. Do not invent scores or call review/finalization tools.

After a reviewed or finalized candidate, the user can describe what to keep and what to change. The Skill presents an auditable preserve/change contract, asks for a separate one-to-three-round revision budget, and creates an immutable child run only after confirmation. It chooses the least destructive mode: same-seed prompt refinement, then low-strength img2img, then inpainting with explicit mask-overlay confirmation. No-mask preservation is best-effort.

For the optional copy-subject-v1 route, the Agent displays both normalized regions as decimals and percentages, both regional prompts and strengths, the exact sdxl-regional-txt2img route, and the successful-round budget before confirmation. The geometry is frozen for that run. Refinement may change regional prompts or strengths, but moving a region requires a newly confirmed root or child; unavailable or drifted regional capability never falls back to prompt-only sdxl-txt2img.

For the optional sdxl-two-stage-copy-subject route, local_gpu_set_model_trust accepts the exact two_stage_layout; callers never provide control_sha256. The server normalizes that layout, inspects the shipped workflow, derives the control digest, and includes the workflow, bundle, and control digests in the displayed trust confirmation. Approval and later routing require the same normalized layout, workflow, component bundle, endpoint, and model identity. The Agent also displays pixel geometry and percentages, the base and derived subject seeds, subject conditioning, and the two-stage budget. One round costs two stage units and retains three role-bound PNGs: a base artifact, mask artifact, and final artifact. Protected-pixel and saved-mask gates run before review; a partial result stops with no fallback. Both base and final receive full-resolution stage review, and only the final artifact can become a candidate. The first live GPU gate is exactly one two-stage round.

The earlier single-pass copy-subject-v1 regional route remains as retained negative evidence and experimental compatibility. Its model-free control contract remains useful, but the observed output does not establish a visual-quality improvement. Neither route is presented as positive image-quality evidence until retained full-resolution acceptance exists.

The adaptive sequence is discovery -> trust when needed -> scoped catalog -> brief -> exact-route recommendation -> post-display confirmation -> start -> read persisted run -> construct complete plan -> generate -> full-resolution inspect -> review -> refine/explore or display candidate -> wait for a later user message -> finalize. The configured max_rounds must be from 1 through 3, and urgency or sunk cost never extends it.

Visual Profiles And Scope

Complete PPT decks are excluded. Frontend code and components are excluded. Production icons, SVG, and transparent PNG are excluded. Automatic segmentation is excluded. Seamless-texture guarantees are excluded. The project produces inspectable raster assets, not slide layouts or interface implementations.

Bring Your Own Model Safely

Discovery has four levels: api_only, selected_folders, common_locations, and full_drive. Filesystem discovery is two-stage: index records bounded metadata without opening checkpoint payloads; fingerprint computes SHA-256 only for explicitly selected indexed candidates. .ckpt remains opaque, and scans do not follow symlinks, junctions, or reparse points.

Trust is stored outside the repository under the OS user-state directory, overridable with LOCAL_GPU_IMAGEGEN_STATE_DIR. A backend_binding identity can be trusted only for private use. For split ComfyUI routes, the trust tool first offers a non-mutating inspection action that binds the primary model, text encoder, VAE, and reviewed workflow into one canonical SHA-256 bundle. The exact bundle digest is part of the later trust confirmation and route token. A cryptographic bundle may become a public_evidence candidate only with exact source, license, and output-redistribution metadata for every component; acceptance authority must approve that same bundle before export.

Safe Workflow Onboarding

Existing ComfyUI API-format workflows can be inspected and registered without caller-supplied node IDs when they are ordinary txt2img graphs using either a single checkpoint or split model topology. The bounded sequence is:

API-only discovery (when current inventory is absent)
-> local_gpu_inspect_workflow
-> display hashes, inferred binding, components, limitations, confirmation
-> later exact user confirmation
-> local_gpu_register_workflow
-> separate local_gpu_set_model_trust with `registered_workflow_id`

Inspection reads one explicit local JSON file, accepts a bare API graph or a unique prompt wrapper, and reports source_sha256, workflow_sha256, topology, inferred binding, owned output, and component identities. Registerable results include register_workflow:<source_sha256>:<proposal_digest>; diagnostic results have no confirmation. UI format is not converted; registration does not grant model trust or public authority. Zero-GPU real-client onboarding evidence is retained; generation evidence remains separate.

No model weights are bundled. The repository catalog includes the auditable ID civitai/anything-v5@30163 for an already reviewed local WebUI checkpoint, and downloads remain unapproved. Other local models can enter the private catalog only through discovery and explicit trust; model quality still comes from the user's model. This project adds safer routing, durable review, and hot revision rather than claiming a superior prompt translator.

ComfyUI ships reviewed sd15-txt2img-v1.json, sdxl-txt2img-v1.json, sdxl-regional-txt2img-v1.json, sdxl-two-stage-copy-subject-v1.json, z-image-turbo-txt2img-v1.json, and anima-txt2img-v1.json workflow files. Discovery distinguishes CheckpointLoaderSimple, UNETLoader, CLIPLoader, and VAELoader. A private backend-bound route may still bind only the primary loader, but public-evidence eligibility for a split workflow requires current API identities plus filesystem SHA-256 identities for every frozen component. A pure split-model installation may have no checkpoint choices. Shell, Python/script/process execution, network/download/webhook/fetch nodes, commands, unknown custom nodes, unbound parameters, and resource overruns are rejected.

The workflow files do not include, install, trust, or license model weights. Z-Image and Anima still require exact local discovery, user approval, and a confirmed route. Anima is an optional anime route and must not be presented as a commercial or public-evidence default under its upstream weight restrictions. ComfyUI adapter: contract-tested; local Z-Image and Anima adapter executions: observed; public acceptance evidence: not retained.

Tool Reference

The public MCP surface has exactly seventeen tools: two compatibility tools and fifteen high-level discovery/onboarding/run/revision tools.

local_gpu_imagegen_check

Reports Python packages, CUDA devices, WebUI reachability, and aggregate readiness. A machine can be not ready while the tool call itself succeeds.

local_gpu_generate_image

Supports:

• txt2img, img2img, and inpainting
• fixed seeds
• WebUI checkpoint and sampler selection
• Diffusers scheduler selection
• LoRA loading
• VAE tiling and optional CPU offload
• explicit CPU fallback
• explicit model/LoRA download permission

The tool schema validates types, ranges, enums, unknown fields, image-mode requirements, and dimensions before starting the backend process.

These two compatibility tools remain available beside the fifteen high-level tools. In particular, the low-level local_gpu_generate_image compatibility tool is unchanged: its optional model value remains a direct compatibility passthrough and is not the catalog-gated Agent workflow. Its WebUI/Diffusers options and explicit model-download controls are unchanged.

High-Level Run Tools

max_rounds must be from 1 through 3. Only successfully retained PNG rounds consume that budget; a backend failure is recorded as an attempt without consuming a round. Every new review requires full_resolution_inspected: true, whether a prominent human is present, and explicit observations for limb separation, feet/contact, hands/held objects, and text/watermarks. Human anatomy checks cannot be not_applicable; any required fail or uncertain result can request only refine or explore.

An eligible review exposes quality status candidate, never acceptance, and binds the run, round, and retained image SHA-256. The Agent displays the original image, limitations, hash, and exact finalize:<run_id>:<round_number>:<image_sha256>, then waits for a later user message. local_gpu_finalize_run requires that exact confirmation plus the nominated round_number and summary. It revalidates the candidate under the run lock, then publishes that nominated reviewed round without substituting a higher-scoring round; only the published result receives accepted.

An ineligible reviewed artifact is never published. Refine or explore while confirmed budget remains; otherwise retain it and request a new user decision without publication. Existing finalized manifests and the lower-level store compatibility path may still contain needs_user_review, but an unfinalized legacy review without structured visual checks cannot produce a public-engine candidate.

local_gpu_list_profiles returns the scoped merged catalog and current capabilities. local_gpu_start_run requires the exact route_token, authorization scope, model, backend, dimensions, workflow, and compiler that were displayed. Identity drift fails before backend invocation; root and child runs never switch routes silently.

Run Files, Retry, And Recovery

The default durable layout is:

outputs/
  runs/
    <run_id>/
      manifest.json
      parent-source.png
      round-01.png
      round-01-preview.jpg
      final.png
      final-upscaled.png
      masks/
        mask-01.png
        mask-01-overlay.jpg

outputs/runs/<run_id>/manifest.json is the source of truth for confirmed input, attempts, rounds, reviews, warnings, final metadata, and state revisions. A successful first round retains round-01.png and may create round-01-preview.jpg; later rounds use the same hyphenated preview pattern. Stored legacy manifests that reference round-01.preview.jpg remain readable and are not rewritten. Finalization publishes final.png. A preview file is optional: the MCP response may include the bounded JPEG preview, while full_image_path identifies the full-resolution local PNG. A preview warning or encoding failure does not discard the validated PNG.

An immutable child run copies the selected parent PNG to parent-source.png, records parent lineage and hashes, and never writes the parent manifest. Img2img and inpaint use that retained source. Inpaint additionally requires a confirmed masks/mask-01.png; masks/mask-01-overlay.jpg is returned for approval first. Changing source or mask bytes invalidates confirmation.

Each generation request needs an idempotency_key. Repeating the same key with the same request returns the completed round or reports that the attempt is busy; reusing the key for different inputs is rejected. After interruption, call local_gpu_get_run and follow recoverable_next_actions. The engine can reclaim stale attempts and resume preview creation when a validated full PNG was already retained.

Cleanup is explicit. For both intermediates and all, confirmation must exactly equal the run_id. The intermediates scope preserves the manifest and published final file; all removes the confirmed run directory.

Optional Anime Real-ESRGAN Postprocess

Anime-only 4x postprocessing is explicit and local. Configure the tool root only with LOCAL_GPU_IMAGEGEN_REALESRGAN_DIR; the server accepts only realesrgan-ncnn-vulkan.exe plus one of the supported model pairs, realesrgan-x4plus-anime or realesr-animevideov3-x4, under that root. It accepts no arbitrary executable path or model name, and it does not download a binary or model.

No postprocessor runs automatically. Even upscale_policy: auto records permission only: the caller must pass the exact postprocess object to local_gpu_finalize_run, and the confirmed style must be anime. A successful request preserves the original final.png, returns final-upscaled.png, and records model, scale, source/output paths, hashes, dimensions, and MIME types in final postprocess metadata. Unavailable or failed postprocessing falls back to the original final with a structured warning. Real binary, GPU, quality, and performance behavior remains unverified.

Standalone Usage

Generate through an already-running WebUI:

python .\scripts\generate_image.py `
  --backend webui `
  --prompt "a small robot reading a circuit diagram, clean concept art" `
  --width 1024 --height 1024 --seed 42

Create a project-local Diffusers environment:

powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1

Diffusers will not fetch missing model files by default. After reviewing the model license and storage requirement, opt in for a specific run:

.\.venv\Scripts\python.exe .\scripts\generate_image.py `
  --backend diffusers `
  --model stabilityai/sd-turbo `
  --allow-download `
  --prompt "a compact lunar research station, technical concept art" `
  --seed 42

Compatibility-tool files default to outputs/. Override this with LOCAL_GPU_IMAGEGEN_OUTPUT_DIR or --output-dir. High-level runs use the runs/<run_id>/ layout under that output root.

Architecture

flowchart LR
    A["MCP client"] -->|"stdio JSON-RPC"| B["Thin MCP server"]
    B --> H["Discovery + trust + capability router"]
    H --> C["Frozen route + durable run engine"]
    C --> E["AUTOMATIC1111 / Forge adapter"]
    C --> I["Reviewed ComfyUI workflow adapter"]
    C --> F["Diffusers compatibility runner"]
    E --> G["Full local PNG + bounded preview"]
    I --> G
    F --> G
    G --> C
    C --> B
    B --> A

The transport layer owns JSON-RPC, schemas, validation, dispatch, timeouts, and structured results. The run engine owns orchestration and delegates durable state to RunStore; backend loading and image generation stay in scripts/generate_image.py.

See Architecture for the detailed control flow and error model.

Safety And Privacy

• The MCP process does not use an application-specific cloud image API.
• A confirmed LAN WebUI/ComfyUI endpoint sends prompts and source images to that server. Loopback is local; each LAN endpoint requires exact transmission confirmation, and public internet endpoints are rejected.
• Discovery does not follow links or load checkpoint payloads. Broader filesystem scans require an unchanged, unexpired plan and exact confirmation.
• Trust state stays outside Git. Private trust never authorizes public evidence, and credentials are rejected recursively.
• scripts/install.ps1 downloads Python packages when the user runs it.
• Diffusers model and LoRA downloads require --allow-download or MCP allow_download: true.
• Disabling a model safety checker is explicit and off by default.
• Input images and generated files remain ordinary local files; protect their directories with OS permissions appropriate to their sensitivity.

See Security before exposing a WebUI API beyond localhost.

Test

The suite requires no GPU and downloads no models:

python -m unittest discover -s tests -v
python .\scripts\verify_mcp.py

Coverage includes protocol initialization/listing/ping, the exact seventeen-tool contract, bounded discovery/onboarding/trust/routing, WebUI and ComfyUI adapter contracts, durable root/child transitions, fixed two-region SDXL route/conditioning/exhaustion behavior, mask confirmation, idempotency, stale-attempt recovery, atomic publication, bounded preview handling, the mocked/model-free anime loop, all nine fixed briefs and three child revisions, fake-runner postprocessing, and download policy.

Project Status

Verified:

• stdio MCP initialization, tool listing, ping, and tool contract
• structured tool success/error results
• fifteen high-level discovery/onboarding/run/revision tools and two compatibility tools under mocked/model-free coverage
• adaptive Agent Skill briefing, exact-model confirmation, successful-round budgeting, and honest text-only stopping policy
• exact local-model identity, user-local trust, deterministic route, and drift-rejection contracts
• explicit anime-only Real-ESRGAN adapter behavior under fake-runner tests
• contract-tested WebUI and ComfyUI adapter success/failure paths
• durable manifest transitions, idempotency, recovery, review, finalization, and cleanup contracts
• three Profile contracts plus immutable preserve/change child runs and confirmed geometry/user masks
• fixed copy/subject geometry, regional conditioning, route drift rejection, and a two-round model-free regional vertical slice
• server-derived two-stage control identity, control-bound trust confirmation, contradictory-binding rejection, and exact model-free route recovery
• a fake-backend contract matrix covering nine fixed briefs and three child revisions
• local-only Diffusers hub policy by default
• installable serve, doctor, verify, config, and read-only-by-default setup CLI contracts, including an isolated wheel smoke test
• official Codex and Claude Code setup-contract parsing plus equivalent exact-seventeen-tool stdio launches; Claude Desktop remains a legacy render-only template

Pending before a 1.0 claim:

• a complete retained 9+3 real host/vision acceptance matrix
• real Real-ESRGAN binary/GPU execution evidence
• additional generated named-client session evidence beyond the retained Codex result, including Claude Code
• measured performance or VRAM data
• any production-readiness claim

The Mocked/model-free matrix is deterministic protocol evidence, not the retained real Codex/vision/GPU result. It exercises nine fixed briefs and three child revisions with a fake backend; it does not prove visual quality. Local Z-Image and Anima calls through the project adapter have been observed, but they are local development validation rather than public acceptance evidence. Historical generated-image records remain technical audit material and are not v0.9 promotional visuals. The test suite does not load a production model, GPU backend, or Real-ESRGAN binary. No production, performance, VRAM, image-quality superiority, guaranteed Star, or broader named-client generation claim is made.

The repository has no approved v0.9 promotional image and no complete real 9+3 image-acceptance matrix. It makes no generalized image-quality, performance, or VRAM claim. Use the readiness commands above to inspect the target environment.

Documentation

• Architecture and error model
• Troubleshooting
• Client compatibility
• Protocol demo boundary
• Release checklist
• Stable Diffusion integration notes
• Contributing
• Changelog

License

Released under the MIT License. Model weights, backend applications, and generated outputs retain their own licenses and terms; none are relicensed by this repository.