🔥 Z-Explorer

AI Image Generation Without the UI Tax
Type a prompt. Get art. That's it.

The Problem • The Solution • Prompt Magic • Installation

---

The Problem

You wanted to make AI art. Instead you got:

• 47 browser tabs of documentation
• A node graph that looks like spaghetti had a baby with a circuit board
• "CUDA out of memory" every 5 minutes
• Settings panels with 200 sliders you don't understand
• That one workflow that worked yesterday but doesn't today

You're spending more time fighting the tool than creating.

We think that's insane.

---

The Solution

Z-Explorer strips away everything between you and your art.

>>> a cute fox in a magical forest

That's it. No nodes. No tabs. No sliders. Just your idea, rendered.

How it works:

1. Type a prompt — natural language, just like talking to a person
2. Hit enter — generation starts instantly
3. See your art — displayed right there, no hunting through folders

Everything runs locally. No cloud. No API keys. No monthly fees. Your GPU, your art, your privacy.

---

Prompt Magic

This is where Z-Explorer shines. We built features that make prompt crafting fun, not tedious.

🎲 Prompt Variables — Randomized Creativity

Tired of typing the same things? Use variables for instant variety:

>>> a __animal__ wearing a crown

Each generation picks a random animal. Run it 10 times, get 10 different creatures.

Variables are just text files. Add your own:

# library/mood.md
ethereal
cyberpunk
cottagecore
dark fantasy
solarpunk

Now use __mood__ anywhere. Your vocabulary, your variables.

🧠 Auto-Generated Variables

Here's where it gets magical. Use a variable that doesn't exist:

>>> a portrait of a __famous_inventor__

Z-Explorer's local LLM generates it on the fly:

✨ Generated __famous_inventor__ with 20 values
   → Nikola Tesla, Ada Lovelace, Leonardo da Vinci...

Saved to your library. Ready for next time.

No more googling "list of famous inventors". Just ask, and it appears.

✨ Prompt Enhancement — From Vague to Vivid

Your prompt: a cat

What the AI actually needs: A majestic orange tabby cat with emerald eyes, sitting on a velvet cushion, soft golden hour lighting streaming through a Victorian window, hyperrealistic fur detail, shallow depth of field, cinematic composition

The > operator bridges that gap:

>>> a cat > make it cozy and magical

The local LLM expands your idea into a rich, detailed prompt. Same intent, 10x better output.

Or use it standalone:

>>> /enhance a robot in a garden

See exactly what the AI will receive before committing.

🔄 Batch Generation — Explore Variations

Want 10 variations? Easy:

>>> a __animal__ in space : x10

Generates 10 images with different animals and seeds. Find the diamond in the rough.

Combine with size control:

>>> epic landscape : x5,w1920,h1080

5 widescreen landscapes. One command.

---

Two Ways to Create

🌐 Web UI (Default)

Launch Z-Explorer and get a beautiful web-based UI:

• Masonry gallery of all your generations
• Fake CLI for that terminal aesthetic (with autocomplete!)
• Live preview — images appear the moment they're done
• Prompt saved with every image

z-explorer

⌨️ CLI Mode (For Purists)

Prefer a pure terminal experience?

z-explorer --cli

Same power, different vibe. Perfect for SSH sessions or terminal lovers.

---

Installation

Prerequisites

• Python 3.10, 3.11, or 3.12 (3.13+ not yet supported)
• NVIDIA GPU with CUDA support (12GB+ VRAM recommended)
• uv — fast Python package manager

One-Command Install

WebUI (recommended)

uvx --python 3.12 z-explorer

CLI Mode (advanced - use Kitty or similar terminal with graphics support)

uvx --python 3.12 z-explorer --cli

That's it! This downloads Z-Explorer from PyPI and launches the setup wizard.

First-Time Setup

On first launch, Z-Explorer guides you through setup:

Step 1: Dependencies

Z-Explorer uses bleeding-edge versions of some libraries that aren't on PyPI yet. The wizard checks and installs them automatically:

📦 Checking dependencies...
  ⚠ sdnq not installed
  ⚠ diffusers needs update (missing ZImagePipeline)

? Install required dependencies now? (Y/n)

Step 2: Model Configuration

? Choose a setup option:
> Quick Start (Recommended for beginners)
  Custom Setup
  Full Quality

Pick "Quick Start" — it downloads optimized models that work great on 12GB GPUs:

• Image model: ~6GB download, ~12GB VRAM
• LLM: ~4GB download, fast inference

The wizard downloads everything automatically. Grab a coffee ☕

Other Options

• Custom Setup — Mix and match model sources (local files, HuggingFace, quantized)
• Full Quality — Maximum quality for 24GB+ GPUs (~15GB download)

For advanced configuration, see docs/CONFIGURATION.md.

Reconfigure Anytime

z-explorer --setup        # Re-run setup wizard
z-explorer --show-config  # Check current configuration

From Source (Development)

git clone https://github.com/pyros-projects/z-Explorer.git
cd z-Explorer
uv sync
uv run z-explorer

---

Commands

Command	Description
/help	Show all commands
/vars	List available prompt variables
/enhance <prompt>	Preview enhanced prompt
/seed <number>	Set seed for reproducibility
/size <WxH>	Set output dimensions (e.g., 1920x1080)
/gpu	Check GPU memory status
/unload	Free GPU memory
/quit	Exit

Prompt Syntax:

__variable__        Random value from variable
__variable:5__      Specific index (5th value)
prompt > instruction   Enhance prompt with instruction
prompt : x10,w1920    Batch with parameters

---

What's Under the Hood

• Z-Image-Turbo — Lightning-fast image generation
• Qwen3-4B — Local LLM for enhancement and variable generation
• FastAPI — Backend API server
• Svelte — Beautiful web UI

Everything runs locally. No internet required after initial setup.

---

Gallery

---

AI art tools are gatekept by complexity.
We're changing that.

---

License

MIT — Go forth and create.