comfy-discord-web/README.md

# Discord ComfyUI Bot

A Discord bot that integrates with ComfyUI to generate AI images and videos through Discord commands.

## Features

- 🎨 **Image Generation** - Generate images using simple prompts or complex workflows
- 🎬 **Video Generation** - Support for video output workflows
- 📝 **Workflow Management** - Load, modify, and execute ComfyUI workflows
- 📤 **Image Upload** - Upload reference images directly through Discord
- 📊 **Generation History** - Track and retrieve past generations
- ⚙️ **Runtime Workflow Modification** - Change prompts, negative prompts, and input images on the fly
- 🔄 **Job Queue System** - Sequential execution prevents server overload

## Quick Start

### Prerequisites

- Python 3.9+
- Discord Bot Token ([create one here](https://discord.com/developers/applications))
- ComfyUI Server running and accessible
- Required packages: `discord.py`, `aiohttp`, `websockets`, `python-dotenv`

### Installation

1. **Clone or download this repository**

2. **Install dependencies**:
   ```bash
   pip install discord.py aiohttp websockets python-dotenv
   ```

3. **Create `.env` file** with your credentials:
   ```bash
   DISCORD_BOT_TOKEN=your_discord_bot_token_here
   COMFY_SERVER=localhost:8188
   ```

4. **Run the bot**:
   ```bash
   python bot.py
   ```

## Configuration

Create a `.env` file in the project root:

```bash
# Required
DISCORD_BOT_TOKEN=your_discord_bot_token
COMFY_SERVER=localhost:8188

# Optional
WORKFLOW_FILE=wan2.2-fast.json
COMFY_HISTORY_LIMIT=10
COMFY_OUTPUT_PATH=C:\Users\YourName\Documents\ComfyUI\output
```

### Configuration Options

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `DISCORD_BOT_TOKEN` | ✅ Yes | - | Discord bot authentication token |
| `COMFY_SERVER` | ✅ Yes | - | ComfyUI server address (host:port) |
| `WORKFLOW_FILE` | ❌ No | - | Path to workflow JSON to load at startup |
| `COMFY_HISTORY_LIMIT` | ❌ No | `10` | Number of generations to keep in history |
| `COMFY_OUTPUT_PATH` | ❌ No | `C:\Users\...\ComfyUI\output` | Path to ComfyUI output directory |

## Usage

All commands use the `ttr!` prefix.

### Basic Commands

```bash
# Test if bot is working
ttr!test

# Generate an image with a prompt
ttr!generate prompt:a beautiful sunset over mountains

# Generate with negative prompt
ttr!generate prompt:a cat negative_prompt:blurry, low quality

# Execute loaded workflow
ttr!workflow-gen

# Queue multiple workflow runs
ttr!workflow-gen queue:5
```

### Workflow Management

```bash
# Load a workflow from file
ttr!workflow-load path/to/workflow.json

# Or attach a JSON file to the message:
ttr!workflow-load
[Attach: my_workflow.json]

# View current workflow changes
ttr!get-current-workflow-changes type:all

# Set workflow parameters
ttr!set-current-workflow-changes type:prompt A new prompt
ttr!set-current-workflow-changes type:negative_prompt blurry
ttr!set-current-workflow-changes type:input_image input/image.png
```

### Image Upload

```bash
# Upload images to ComfyUI
ttr!upload
[Attach: image1.png, image2.png]

# Upload to specific folder
ttr!upload type:temp
[Attach: reference.png]
```

### History

```bash
# View recent generations
ttr!history

# Retrieve images from a past generation
ttr!get-history <prompt_id>
ttr!get-history 1  # By index
```

### Command Aliases

Many commands have shorter aliases:

- `ttr!generate` → `ttr!gen`
- `ttr!workflow-gen` → `ttr!wfg`
- `ttr!workflow-load` → `ttr!wfl`
- `ttr!get-history` → `ttr!gh`
- `ttr!get-current-workflow-changes` → `ttr!gcwc`
- `ttr!set-current-workflow-changes` → `ttr!scwc`

## Architecture

The bot is organized into focused, maintainable modules:

```
the-third-rev/
├── config.py              # Configuration and constants
├── job_queue.py           # Job queue system
├── workflow_manager.py    # Workflow manipulation
├── workflow_state.py      # Runtime state management
├── discord_utils.py       # Discord utilities
├── bot.py                 # Main entry point (~150 lines)
├── comfy_client.py        # ComfyUI API client (~650 lines)
└── commands/              # Command handlers
    ├── generation.py      # Image/video generation
    ├── workflow.py        # Workflow management
    ├── upload.py          # File uploads
    ├── history.py         # History retrieval
    └── workflow_changes.py # State management
```

### Key Design Principles

- **Dependency Injection** - Dependencies passed via constructor
- **Single Responsibility** - Each module has one clear purpose
- **Configuration Centralization** - All config in `config.py`
- **Command Separation** - Commands grouped by functionality
- **Type Safety** - Modern Python type hints throughout

## Development

### Adding a New Command

See `QUICK_START.md` for quick examples or `DEVELOPMENT.md` for comprehensive guide.

Basic example:

```python
# commands/your_module.py

def setup_your_commands(bot, config):
    @bot.command(name="hello")
    async def hello(ctx):
        await ctx.reply("Hello!", mention_author=False)
```

Register in `commands/__init__.py`:

```python
from .your_module import setup_your_commands

def register_all_commands(bot, config):
    # ... existing ...
    setup_your_commands(bot, config)
```

### Documentation

- **README.md** (this file) - Project overview and setup
- **QUICK_START.md** - Quick reference for common tasks
- **DEVELOPMENT.md** - Comprehensive development guide
- **CLAUDE.md** - Architecture documentation for Claude Code

## Workflow System

The bot supports two generation modes:

### 1. Prompt Mode (Simple)

Uses a workflow template with a KSampler node:

```bash
ttr!generate prompt:a cat negative_prompt:blurry
```

The bot automatically finds and replaces:
- Positive prompt in CLIPTextEncode node (title: "Positive Prompt")
- Negative prompt in CLIPTextEncode node (title: "Negative Prompt")
- Seed values (randomized each run)

### 2. Workflow Mode (Advanced)

Execute full workflow with runtime modifications:

```bash
# Set workflow parameters
ttr!set-current-workflow-changes type:prompt A beautiful landscape
ttr!set-current-workflow-changes type:input_image input/reference.png

# Execute workflow
ttr!workflow-gen
```

The bot:
1. Loads the workflow template
2. Applies runtime changes from WorkflowStateManager
3. Randomizes seeds
4. Executes on ComfyUI server
5. Returns images/videos

### Node Naming Conventions

For workflows to work with dynamic updates, nodes must follow naming conventions:

- **Positive Prompt**: CLIPTextEncode node with title containing "Positive Prompt"
- **Negative Prompt**: CLIPTextEncode node with title containing "Negative Prompt"
- **Input Image**: LoadImage node (any title)
- **Seeds**: Any node with `inputs.seed` or `inputs.noise_seed`

## Troubleshooting

### Bot won't start

**Issue**: `AttributeError: module 'queue' has no attribute 'SimpleQueue'`

**Solution**: This was fixed by renaming `queue.py` to `job_queue.py`. Make sure you're using the latest version.

### ComfyUI connection issues

**Issue**: `ComfyUI client is not configured`

**Solution**:
1. Check `.env` file has `DISCORD_BOT_TOKEN` and `COMFY_SERVER`
2. Verify ComfyUI server is running
3. Test connection: `curl http://localhost:8188`

### Commands not responding

**Issue**: Bot online but commands don't work

**Solution**:
1. Check bot has Message Content Intent enabled in Discord Developer Portal
2. Verify bot has permissions in Discord server
3. Check console logs for errors

### Video files not found

**Issue**: `Failed to read video file`

**Solution**:
1. Set `COMFY_OUTPUT_PATH` in `.env` to your ComfyUI output directory
2. Check path uses correct format for your OS

## Advanced Usage

### Batch Generation

Queue multiple workflow runs:

```bash
ttr!workflow-gen queue:10
```

Each run uses randomized seeds for variation.

### Custom Workflows

1. Design workflow in ComfyUI
2. Export as API format (Save → API Format)
3. Load in bot:
   ```bash
   ttr!workflow-load path/to/workflow.json
   ```
4. Modify at runtime:
   ```bash
   ttr!set-current-workflow-changes type:prompt My prompt
   ttr!workflow-gen
   ```

### State Persistence

Workflow changes are automatically saved to `current-workflow-changes.json` and persist across bot restarts.

## Contributing

We welcome contributions! Please:

1. Read `DEVELOPMENT.md` for coding guidelines
2. Follow existing code style and patterns
3. Test your changes thoroughly
4. Update documentation as needed

## License

[Your License Here]

## Support

For issues or questions:
- Check the troubleshooting section above
- Review `DEVELOPMENT.md` for implementation details
- Check ComfyUI documentation for workflow issues
- Open an issue on GitHub

## Credits

Built with:
- [discord.py](https://github.com/Rapptz/discord.py) - Discord API wrapper
- [ComfyUI](https://github.com/comfyanonymous/ComfyUI) - Stable Diffusion GUI
- [aiohttp](https://github.com/aio-libs/aiohttp) - Async HTTP client
- [websockets](https://github.com/python-websockets/websockets) - WebSocket implementation