🎨 Kiko Creator

A modern, web-based AI image generation interface for ComfyUI with character selection, real-time progress tracking, and gallery management.

🌟 Features

Core Functionality

🎨 Real-Time Generation: WebSocket-based progress tracking with live step updates
👤 Character Selection: Browse and search 5328+ anime characters with thumbnails
🎯 Smart Model Management: Auto-sync checkpoints and LoRAs from ComfyUI
🖼️ Gallery System: Persistent gallery with favorites, batch operations, and metadata
📱 Responsive Design: Mobile-first UI with touch-optimized controls
🌙 Dark Mode: Beautiful dark theme optimized for extended use

Character System

5328+ Characters: Pre-loaded character database from WAI dataset
Custom Characters: Create and manage your own custom characters with images
Smart Search: Real-time search with fuzzy matching
Infinite Scroll: Smooth browsing with virtual scrolling
Thumbnail Gallery: Character previews with metadata
Right-Click Menu: Quick actions (send to prompt, delete, edit)

Generation Features

Advanced Settings: Steps, CFG, sampler, scheduler, resolution presets
💾 Preset System: Save and load complete generation settings
- Save Presets: Capture all settings (checkpoint, prompts, LoRAs, steps, CFG, resolution, CLIP skip, hires fix, refiner)
- Searchable Dropdown: Quick access with search and favorites (⭐)
- One-Click Apply: Instantly restore your favorite configurations
- Persistent Storage: Presets saved locally and sync across sessions
🎨 CLIP Skip: Control text encoder layer selection
- Range from -1 (last layer) to -12 (12th layer from end)
- Default -2 (SDXL standard) for optimal quality
- Fine-tune how the AI interprets your prompts
- Saved with presets for consistent results
LoRA Management: Drag-and-drop LoRA slots with strength controls
🎯 LoRA Trigger Words: Active trigger words displayed beneath prompt as clickable tags
- Click individual tags to add to prompt
- "Add All" button for quick insertion
- Automatically reads from LoRA Manager .metadata.json and safetensors metadata
- Shows combined trigger words from all selected LoRAs
Tag Autocomplete: Danbooru/E621 tag suggestions (ready for integration)
Wildcard Support: Random prompt generation from text files
View Tags: Angle, camera, background, and style tags
Batch Generation: Generate multiple images at once
Seed Control: Random or fixed seeds with manual override
Real-Time Progress: WebSocket connection shows actual step progress

Gallery & Organization

Persistent Storage: Images saved with full metadata in localStorage
Grid View: Adjustable 2-6 column layouts
Lightbox: Fullscreen viewer with keyboard navigation (ESC, arrows)
Favorites: Star important generations
Batch Operations: Multi-select for download/delete
Metadata Display: View all generation parameters

Models Management

Checkpoint Browser: View all available checkpoints with thumbnails
LoRA Browser: Browse LoRA library with metadata
CivitAI Integration: 🌐 Globe links to CivitAI model pages (uses LoRA Manager metadata)
🔄 Model Re-scanning: One-click re-scan to discover new models and update metadata
- Professional modal UI with loading/success/error states
- Shows detailed statistics (checkpoints, LoRAs, embeddings, cached count, duration)
- Automatically reloads trigger words and metadata after scan
- Preserves previous scan settings (YAML path, CivitAI integration)
Quick Send: One-click send models to generation page
Folder Organization: Models grouped by directory structure
Auto-Sync: Real-time model list from ComfyUI API
Extra Model Paths: Automatically discovers models from extra_model_paths.yaml
Database Management: Vacuum, optimize, and backup database operations

📋 Prerequisites

Required

Node.js 18+ (with npm)
ComfyUI with ComfyUI_Mira v0.4.9.2+
Python 3.10+ (for ComfyUI)

Optional (Recommended)

Python 3.8+ (for enhanced safetensors metadata reading - see Python Helper Setup)
ComfyUI-Lora-Manager by willmiao (for CivitAI metadata and 🌐 globe links)

🚀 Installation

1. Clone the Repository

git clone git clone https://github.com/yourusername/kiko-creator.git
cd kiko-creator

2. Install Dependencies

# Install frontend dependencies
npm install

# Install backend dependencies
cd server
npm install
cd ..

3. Configure Environment

Create a .env file in the root directory:

# Frontend Environment Variables
VITE_API_URL=http://localhost:3001

# ComfyUI API URL
# For local ComfyUI:
VITE_COMFYUI_URL=http://127.0.0.1:8188

# For remote ComfyUI with HTTPS:
# VITE_COMFYUI_URL=https://your-comfyui-server.com

Create a server/.env file:

# Backend Environment Variables
PORT=3001
COMFYUI_API_URL=http://127.0.0.1:8188

# Optional: For CivitAI metadata and extra model paths support
# Requires ComfyUI-LoRA-Manager for enhanced metadata extraction
COMFYUI_MODELS_PATH=/path/to/ComfyUI/models
COMFYUI_DIR=/path/to/ComfyUI

4. Start the Application

# Development mode (frontend only - backend runs separately)
npm run dev

# In another terminal, start the backend:
cd server
npm run dev

# Or use convenience scripts:
./start.sh     # Start both servers in background
./status.sh    # Check server status
./stop.sh      # Stop all servers

5. Access the Application

Open your browser to http://localhost:5173

🔧 ComfyUI Setup

Required Custom Nodes

ComfyUI_Mira (v0.4.9.2 or higher)

cd ComfyUI/custom_nodes
git clone https://github.com/mirabarukaso/ComfyUI_Mira.git

Install Dependencies

cd ComfyUI_Mira
pip install -r requirements.txt

Enable DEV Mode in ComfyUI settings

Optional: CivitAI Metadata Support

For enhanced CivitAI integration with 🌐 globe links to model pages:

Install ComfyUI-LoRA-Manager (recommended)

cd ComfyUI/custom_nodes
git clone https://github.com/willmiao/ComfyUI-Lora-Manager.git

How it works:
- Kiko Creator reads metadata from LoRA Manager's .metadata.json files
- When you download models via LoRA Manager, it stores CivitAI model IDs
- Globe icons (🌐) appear next to models with CivitAI metadata
- Click the globe to view model details on CivitAI
Configuration:
- Set COMFYUI_MODELS_PATH in server/.env to enable metadata reading
- Set COMFYUI_DIR to parse ComfyUI's extra_model_paths.yaml
- Works for checkpoints, LoRAs, and embeddings

Workflow Configuration

Kiko Creator generates ComfyUI workflows programmatically. The workflow builder supports:

Text-to-Image: Standard SD/SDXL generation
LoRA Integration: Multi-LoRA support with strength controls
Hires Fix: Upscaling with customizable denoise
Refiner Support: SDXL refiner integration
Custom Resolutions: SDXL presets and custom sizes

The workflow is built in server/services/workflowBuilder.js and follows ComfyUI_Mira's node structure.

Example Workflow Nodes

The generated workflow includes these key nodes:

KikoPromptNode: Prompt processing with character injection
CheckpointLoaderSimple: Model loading
LoraLoader: LoRA application (multiple chained)
KSampler: Generation with progress tracking
VAEDecode: Latent to image conversion
SaveImage: Output with metadata

🌐 Remote ComfyUI Setup

WebSocket Requirements

Important: If you're running ComfyUI on a remote server and need WebSocket support for real-time progress tracking, the WebSocket connection must originate from localhost due to browser security policies.

Option 1: Using socat (Linux/Mac)

Create a local proxy that forwards WebSocket connections to your remote ComfyUI:

# Install socat
sudo apt-get install socat  # Ubuntu/Debian
brew install socat          # macOS

# Create WebSocket proxy (replace with your remote IP/domain)
socat TCP-LISTEN:8188,bind=127.0.0.1,fork TCP:10.0.140.30:8188

# Or for a remote domain:
socat TCP-LISTEN:8188,bind=127.0.0.1,fork TCP:comfy.yourdomain.com:443

This creates a local proxy at 127.0.0.1:8188 that forwards all traffic to your remote ComfyUI server.

Then configure your .env:

VITE_COMFYUI_URL=http://127.0.0.1:8188

Option 2: Using SSH Tunnel

# Forward remote ComfyUI to localhost
ssh -L 8188:localhost:8188 user@remote-comfyui-server

# Keep this terminal open while using Kiko Creator

Then configure your .env:

VITE_COMFYUI_URL=http://127.0.0.1:8188

Option 3: Nginx Reverse Proxy with SSL

If you control the remote server, set up Nginx to handle both HTTP and WebSocket with SSL:

server {
    listen 443 ssl http2;
    server_name comfy.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:8188;
        proxy_http_version 1.1;

        # WebSocket support
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        # Standard proxy headers
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Timeout settings for long-running generations
        proxy_read_timeout 600s;
        proxy_send_timeout 600s;
    }
}

Then configure your .env:

VITE_COMFYUI_URL=https://comfy.yourdomain.com

Why is this needed?

Modern browsers enforce Mixed Content Policy and Content Security Policy (CSP):

If your app is served over http://, WebSocket connections must use ws://
If your app is served over https://, WebSocket connections must use wss://
The WebSocket connection must be to an allowed origin in the CSP

By proxying through localhost or using proper SSL, you ensure the WebSocket connection meets these security requirements.

🐍 Python Helper Setup (Optional but Recommended)

Kiko Creator includes an optional Python helper for robust safetensors metadata reading. The app works perfectly without Python using a JavaScript fallback, but the Python helper provides better compatibility with large model files and edge cases.

Why Use Python Helper?

With Python Helper:

✅ Uses the official safetensors library (same as ComfyUI)
✅ Handles all format variations and edge cases automatically
✅ Efficient reading of 7GB+ model files
✅ Future-proof with library updates

Without Python Helper (JavaScript Fallback):

✅ Still fully functional - no Python required!
✅ Works for 99% of model files
✅ 700,000x faster than old code (reads only 10KB vs entire file)
⚠️ Manual format parsing (may miss rare edge cases)

Installation

Option 1: Virtual Environment (Recommended)

# Navigate to project root
cd kiko-creator

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
source venv/bin/activate    # Linux/Mac
# OR
venv\Scripts\activate       # Windows

# Install Python dependencies
pip install -r requirements.txt

Option 2: Global Installation

# Install directly (not recommended for production)
pip install -r requirements.txt

Verifying Setup

After installation, restart the server and check the logs:

npm run dev:all

Look for one of these messages in the terminal:

✅ [Safetensors] Using Python helper at /path/to/python - Python helper active!
⚠️ [Safetensors] Python not found, using JavaScript fallback - JS fallback mode (still works!)
⚠️ [Safetensors] Python found but safetensors library not installed - Need to run pip install

What Gets Improved?

The Python helper enhances:

LoRA Metadata Reading: Trigger words, base model info, descriptions
CivitAI Integration: Model/version IDs for 🌐 globe links
Large Model Support: Reads 7GB+ files without memory issues
Edge Case Handling: Unusual format variations handled automatically

Deactivating Virtual Environment

When you're done working with the project:

# Deactivate virtual environment
deactivate

Next time you work on the project, remember to activate the venv again:

source venv/bin/activate  # or venv\Scripts\activate on Windows

More Information

For detailed troubleshooting and testing instructions, see PYTHON_SETUP.md.

📁 Project Structure

kiko-creator/
├── src/                          # Frontend source
│   ├── components/
│   │   ├── layout/              # Layout components
│   │   ├── wizard/              # Setup wizard
│   │   ├── ImageLightbox.jsx    # Image viewer
│   │   ├── TagAutocomplete.jsx  # Tag suggestions
│   │   └── WildcardMenu.jsx     # Wildcard selector
│   ├── pages/
│   │   ├── CharactersPage.jsx   # Character browser
│   │   ├── GeneratePage.jsx     # Main generation UI
│   │   ├── GalleryPage.jsx      # Image gallery
│   │   ├── ModelsPage.jsx       # Model management
│   │   └── SettingsPage.jsx     # App settings
│   ├── stores/
│   │   ├── settingsStore.js     # App configuration
│   │   ├── generationStore.js   # Generation state
│   │   ├── charactersStore.js   # Character data
│   │   └── galleryStore.js      # Gallery persistence
│   └── styles/
│       └── index.css            # Global styles & Tailwind
├── server/                       # Backend API
│   ├── routes/
│   │   ├── setup.js             # Setup endpoints
│   │   ├── generation.js        # Generation API
│   │   ├── comfyui.js          # ComfyUI proxy
│   │   ├── characters.js        # Character data
│   │   └── models.js            # Model scanning
│   ├── services/
│   │   └── workflowBuilder.js   # ComfyUI workflow generation
│   ├── utils/
│   │   ├── safetensors.js       # Safetensors metadata (hybrid JS/Python)
│   │   ├── safetensors_reader.py # Python safetensors helper
│   │   └── python_bridge.js     # Node.js ↔ Python bridge
│   └── index.js                 # Express server
├── data/                         # Data files (git-ignored)
│   ├── wai_characters.csv       # Character database
│   ├── wai_character_thumbs.json # Character thumbnails
│   └── danbooru_e621_merged.csv # Tag autocomplete
├── venv/                         # Python virtual environment (optional)
├── requirements.txt              # Python dependencies
├── PYTHON_SETUP.md              # Python helper documentation
└── referance/                    # Reference application
    └── character_select_stand_alone_app/

🎯 Usage

First-Time Setup

Launch the App: Navigate to http://localhost:5173
Setup Wizard: Configure ComfyUI connection and scan models
Verify Connection: Green indicator shows ComfyUI is connected

Generating Images

Select Character (optional): Browse characters page and click to send to prompt
Configure Settings:
- Choose checkpoint model from dropdown (synced from ComfyUI)
- Adjust steps, CFG, sampler
- Select resolution preset
- Add LoRAs if desired
- Adjust CLIP Skip (-2 is SDXL default, -1 for last layer, up to -12 for early layers)
Enter Prompts: Common prompt + character-specific prompt
Generate: Click generate and watch real-time progress
- Progress bar shows actual steps (e.g., "15/20 - 75%")
- WebSocket provides instant updates
View Results: Images appear in preview and are saved to gallery

Using Presets

Save a Preset:

Configure your desired settings (checkpoint, prompts, LoRAs, steps, CFG, resolution, CLIP skip, hires fix, refiner)
Click the ⚙️ Presets button in the top right
Enter a preset name and click Save
Your preset is now saved locally

Load a Preset:

Click the dropdown next to the Presets button
Search for your preset by name
Click on a preset to instantly apply all saved settings
Star (⭐) your favorite presets for quick access

Preset Features:

Complete Settings: Saves everything - checkpoint, prompts, LoRAs with strengths, generation parameters, CLIP skip, hires fix, and refiner settings
Search & Filter: Type to find presets quickly, filter by favorites
Persistent: Presets sync across browser sessions
Import/Export: Share presets with others (coming soon)

Managing Gallery

View All Images: Navigate to Gallery page
Adjust Grid: Use slider for 2-6 column layouts
Filter Favorites: Click "⭐ Favorites" to show starred images
Batch Operations: Enable selection mode for multi-delete/download
Lightbox: Click any image for fullscreen view
- Press ESC to close
- Use arrow keys to navigate
- View full metadata

Model Management

Browse Models: Navigate to Models page
Switch Tabs: Toggle between Checkpoints and LoRAs
Search: Filter by name or folder
Send to Generation: Click "➤ Generate" on any model card
CivitAI Links: Click 🌐 globe icon to view model details on CivitAI (requires LoRA Manager)
View Details: Click "ℹ️ Info" for CivitAI metadata (when available)
Auto-Refresh: Models sync automatically from ComfyUI on page load
Dropdowns: Globe icons also appear in model/LoRA/embedding selection dropdowns for quick access

Using LoRA Trigger Words

Select a LoRA: Add any LoRA to a slot in the generation page
Trigger Words Appear: Tags automatically display beneath the positive prompt
Click to Add: Click individual trigger word tags to add them to your prompt
Add All: Use the "Add All" button to insert all trigger words at once
Multiple LoRAs: Trigger words from all selected LoRAs are combined and deduplicated

Note: Trigger words are automatically extracted from:

LoRA Manager .metadata.json files (if installed)
Safetensors metadata embedded in model files
CivitAI metadata (if previously scanned with API key)

Re-scanning Models

When you add new models to ComfyUI or update existing ones:

Navigate to Settings: Go to Settings page
Find Model Management: Scroll to the "Model Management" section
Click Re-scan: Press the "Re-scan Models" button
Watch Progress: A modal shows the scanning progress with a spinner
View Results: When complete, see statistics:
- Checkpoints discovered
- LoRAs discovered (with trigger words)
- Embeddings discovered
- Cached vs new models
- Scan duration
Automatic Reload: Models and trigger words update automatically after scan

🙏 Credits & Acknowledgments

Reference Application

Kiko Creator is inspired by and builds upon concepts from:

Character Select Stand Alone App by @mirabarukaso

This reference application provided invaluable patterns and concepts:

Character database structure and selection system
Tag autocomplete mechanism from Danbooru/E621
LoRA slot management patterns
ComfyUI workflow generation logic
CSV data file formats and processing

CivitAI Integration

ComfyUI-Lora-Manager by willmiao

Kiko Creator reads CivitAI metadata from LoRA Manager's .metadata.json files to provide:

Direct links to model pages on CivitAI
Model version information
Seamless integration with CivitAI's download workflow

Key Differences

While inspired by the reference app, Kiko Creator is a complete reimplementation with significant architectural changes:

Architecture

Web-First: React SPA instead of Electron desktop app
Modern Stack: React + Express instead of vanilla JS + Electron IPC
No Bundling: Vite HMR instead of Electron build process

Features

Real-Time Updates: WebSocket progress instead of HTTP polling
Persistent Gallery: localStorage with full metadata instead of temp preview
Responsive Design: Mobile-optimized UI with touch support
Model Browser: Visual model management vs filesystem scanning only
Dark Mode Only: Optimized single-theme design
Auto-Sync: Models sync from ComfyUI API vs manual file scanning

Technical Implementation

State Management: Zustand with persist vs vanilla state
API Layer: REST + WebSocket vs Electron IPC
Component System: React hooks vs vanilla DOM manipulation
Styling: Tailwind CSS + Framer Motion vs custom CSS

Data Sources

Character Database: WAI Characters dataset (5328+ characters)
Tag Database: Danbooru/E621 merged tag collection
Character Thumbnails: Curated thumbnail collection from reference app

Technologies

Frontend

React 18.3 - UI framework with hooks
Vite 5.x - Build tool and dev server
Tailwind CSS 3.x - Utility-first CSS
Framer Motion - Animation library
Zustand - Lightweight state management
React Router 6.x - Client-side routing

Backend

Node.js 18+ - JavaScript runtime
Express 4.x - Web server framework
Axios - HTTP client for ComfyUI API
YAML - Configuration file parsing

Integration

ComfyUI - Stable Diffusion backend
ComfyUI_Mira - Essential extension for workflow support
WebSocket - Real-time progress tracking

🐛 Known Issues & Limitations

Current Limitations

Tag autocomplete requires CSV data files (auto-download planned)
CivitAI metadata requires ComfyUI-LoRA-Manager to be installed (see Setup)
WebSocket requires proxy for remote ComfyUI without HTTPS (see Remote Setup)
Gallery stored in browser localStorage (limited to ~10MB)

Workarounds

Remote WebSocket: Use socat or SSH tunnel (documented above)
Storage Limits: Clear old images when approaching browser limits
Model Sync: Refresh Models page if new models don't appear

🚧 Roadmap

Completed ✅

In Progress 🚧

Tag autocomplete with weight adjustment
Wildcard browser and editor

Planned 📋

🤝 Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Guidelines

Follow existing code style
Add comments for complex logic
Test on both desktop and mobile
Update documentation as needed

📧 Support

For issues and questions:

GitHub Issues: Report a bug or request a feature
Documentation: Check this README and inline code comments
Reference App: Check the Character Select Stand Alone App for original patterns

📄 License

MIT License - See LICENSE file for details

🌟 Show Your Support

If you find this project useful:

⭐ Star the repository
🐛 Report bugs and suggest features
📢 Share with the ComfyUI community
🤝 Contribute improvements

Made with ❤️ for the ComfyUI community

Inspired by and grateful to the Character Select Stand Alone App team for their excellent reference implementation.

🔗 Quick Links

ComfyUI - Main SD backend
ComfyUI_Mira - Required extension
ComfyUI-Lora-Manager - LoRA metadata provider by willmiao
Character Select App - Reference implementation
Tailwind CSS - CSS framework
React - UI library

Name		Name	Last commit message	Last commit date
Latest commit History 66 Commits
AppIcons		AppIcons
docs		docs
server		server
src		src
.env.example		.env.example
.gitignore		.gitignore
CSP_CONFIG.md		CSP_CONFIG.md
LICENSE		LICENSE
README.md		README.md
index.html		index.html
package.json		package.json
plan.md		plan.md
postcss.config.js		postcss.config.js
requirements.txt		requirements.txt
restart.sh		restart.sh
start.sh		start.sh
status.sh		status.sh
stop.sh		stop.sh
tailwind.config.js		tailwind.config.js
vite.config.js		vite.config.js

Folders and files

Latest commit

History

Repository files navigation

🎨 Kiko Creator

🌟 Features

Core Functionality

Character System

Generation Features

Gallery & Organization

Models Management

📋 Prerequisites

Required

Optional (Recommended)

🚀 Installation

1. Clone the Repository

2. Install Dependencies

3. Configure Environment

4. Start the Application

5. Access the Application

🔧 ComfyUI Setup

Required Custom Nodes

Optional: CivitAI Metadata Support

Workflow Configuration

Example Workflow Nodes

🌐 Remote ComfyUI Setup

WebSocket Requirements

Option 1: Using socat (Linux/Mac)

Option 2: Using SSH Tunnel

Option 3: Nginx Reverse Proxy with SSL

Why is this needed?

🐍 Python Helper Setup (Optional but Recommended)

Why Use Python Helper?

Installation

Option 1: Virtual Environment (Recommended)

Option 2: Global Installation

Verifying Setup

What Gets Improved?

Deactivating Virtual Environment

More Information

📁 Project Structure

🎯 Usage

First-Time Setup

Generating Images

Using Presets

Managing Gallery

Model Management

Using LoRA Trigger Words

Re-scanning Models

🙏 Credits & Acknowledgments

Reference Application

CivitAI Integration

Key Differences

Architecture

Features

Technical Implementation

Data Sources

Technologies

Frontend

Backend

Integration

🐛 Known Issues & Limitations

Current Limitations

Workarounds

🚧 Roadmap

Completed ✅

In Progress 🚧

Planned 📋

🤝 Contributing

Development Guidelines

📧 Support

📄 License

🌟 Show Your Support

🔗 Quick Links

About

Resources

License

Uh oh!

Stars

Watchers

Packages