# Claude Code / Codex Rules

Drop this file as `CLAUDE.md` at the root of your admin repo (the one with `server/`).
It tells Claude Code / Codex how to help you with the ComfyUI serverless deployment safely.

---

# Project: ComfyUI Serverless Admin

## What this is

This is the admin config for a ComfyUI deployment running on fal.ai serverless GPUs.

The user edits `server/` to add models, custom nodes, and deps. The rest of the system (proxy, frontend, wheel) is managed separately — do NOT modify it.

## Editable files

**Only modify these files:**
- `server/comfy.py` — models (`MODELS` dict), custom nodes (`CUSTOM_NODES` list), ComfyUI version (`COMFY_COMMIT_HASH`, `REPO_NAME`)
- `server/requirements.txt` — Python dependencies

## Do NOT modify

- `proxy/` — the local proxy, managed separately
- `wheel/` — the custom serverless-comfy wheel, managed separately
- `server/server.py` — the fal.App class and patches (unless explicitly asked)
- `frontend/` — ComfyUI frontend build
- `run.sh`, `run.ps1`, `run.bat`

## Workflow

### Add a model

1. Identify the correct folder (see `docs/ADD_MODELS.md`):
   - Checkpoints → `checkpoints`
   - FLUX/WAN/Qwen diffusion → `diffusion_models`
   - LoRAs → `loras`
   - VAE → `vae`
   - CLIP/text encoders → `clip`
   - Upscale → `upscale_models`
   - Latent upscale (LTX spatial/temporal) → `latent_upscale_models`

2. Add to `server/comfy.py` in the right section:
   ```python
   ["filename.safetensors", "https://huggingface.co/.../filename.safetensors"]
   ```

3. Verify the URL is public and downloadable.

### Add a custom node

1. Find the latest **stable** commit on GitHub (at least 1 day old — fal shallow clone may fail on very recent commits).

2. Pin it explicitly:
   ```python
   ["https://github.com/USER/REPO.git", "40-char-commit-hash"]
   ```

3. Check the node's `requirements.txt` on GitHub. Add any new Python deps to `server/requirements.txt` with pinned versions.

### Deploy

```bash
cd server
make deploy
```

Runners don't auto-update — they keep running old code until terminated.

## Safety rules

1. **Always pin versions** (`==` for pip, commit SHA for git). Never `main` or `latest`.
2. **Verify URLs** before pinning (`curl -I <url>` should return 200 or 302).
3. **Test after deploy** — watch the runner logs for import errors.
4. **Never delete** models or custom nodes without asking — others may depend on them.
5. **Never change `REPO_NAME`** unless explicitly asked — it forces a full re-clone.
6. **Never change `COMFY_COMMIT_HASH`** unless explicitly asked — breaking change for all workflows.

## Debugging

When something breaks:
1. First check the **runner logs** at https://fal.ai/dashboard/apps/<org>/<app>/runners
2. Look for `ImportError`, `size mismatch`, `RuntimeError`
3. If it's a missing Python module → add to `requirements.txt`
4. If it's a model size mismatch → ComfyUI version incompatible with the model
5. If it's a custom node import error → check the node's GitHub issues

## Commands

```bash
# Deploy
cd server && make deploy

# Check currently loaded models (while proxy is running)
curl -s --compressed http://localhost:8188/api/experiment/models/checkpoints

# Check available nodes
curl -s --compressed http://localhost:8188/api/object_info | jq 'keys | length'

# Kill runner (from CLI — for brave souls)
# (Use the dashboard UI instead: easier)
```

## Communication

- Logs: https://fal.ai/dashboard/apps/<org>/<app>/runners
- Docs: `docs/` folder
- When asking Lovis for help, include:
  - Runner ID (shown in `./run.sh` output)
  - Screenshot of the UI error
  - Last 50 lines of runner logs
