| # GitHub Copilot — repo orientation |
|
|
| Thin pointer. The canonical agent context lives in [`CLAUDE.md`](../CLAUDE.md) |
| at the repo root — read that first for source-of-truth conventions, dev-sync |
| rules, release rules, fork policy, and trigger phrases. This file only carries |
| the high-stability orientation that helps Copilot place a request before it |
| follows links. |
|
|
| ## What this repo is |
|
|
| ComfyUI-Koolook is a custom-node pack for ComfyUI. Two shipped surfaces: |
|
|
| 1. **Kforge Labs sidebar** — the main user-facing experience. A ComfyUI |
| sidebar tab that saves favorite nodes, workflows (with subdirectories + |
| archive + tags + reusable modules), and full-state snapshots to a |
| configurable on-disk library. |
| - Front-end entry: [`web/koolook_sidebar.js`](../web/koolook_sidebar.js); |
| module bodies under [`web/sidebar/`](../web/sidebar/). |
| - Back-end snapshot/preset routes: [`koolook_routes.py`](../koolook_routes.py) |
| (registers `/koolook/presets/*` aiohttp routes on ComfyUI's PromptServer). |
| - Bundled visual onboarding guide: [`web/guide/index.html`](../web/guide/index.html) |
| (also opened in-app via the sidebar's Tools-row Help button). |
| |
| 2. **Koolook custom nodes** — Python node classes at the repo root, each |
| exposing the standard ComfyUI node contract (`INPUT_TYPES`, `RETURN_TYPES`, |
| `RETURN_NAMES`, `FUNCTION`, `CATEGORY`): |
| - [`k_easy_wan22_prompt.py`](../k_easy_wan22_prompt.py) → `EasyWan22Prompt` |
| (reads [`config.json`](../config.json) at import time — edits to |
| `config.json` need a ComfyUI restart). |
| - [`k_easy_resize.py`](../k_easy_resize.py) → `EasyResize_Koolook` |
| (deprecated alias `EasyResize` still registered for back-compat). |
| - [`k_ai_pipeline.py`](../k_ai_pipeline.py) → `EasyAIPipeline` (paired |
| with front-end widgets in [`web/ai_pipeline.js`](../web/ai_pipeline.js)). |
| - [`k_easy_image_batch.py`](../k_easy_image_batch.py) → `easy_ImageBatch`. |
| - [`k_easy_track.py`](../k_easy_track.py) → `KoolookLoadCameraPosesAbsolute`. |
| - [`k_video_combine.py`](../k_video_combine.py) → `Easy_VideoCombine` |
| (runtime subclass of VHS `VideoCombine`; self-skips if VHS not installed). |
| - Radiance VAE wrappers under |
| [`forks/radiance_koolook/versions/v2_3_3/`](../forks/radiance_koolook/versions/v2_3_3/) |
| → `Easy_hdr_VAE_encode`, `Easy_hdr_VAE_decode`. |
| |
| [`__init__.py`](../__init__.py) imports each module's `NODE_CLASS_MAPPINGS` / |
| `NODE_DISPLAY_NAME_MAPPINGS` and exposes the merged set plus `WEB_DIRECTORY`. |
|
|
| ## Things that bite if you don't know them |
|
|
| - **Backward compatibility is opt-in for Koolook-created nodes only** (the root |
| `k_*.py` custom nodes). For those, make the cleanest change by default — |
| rename/drop/reorder IDs, inputs, and outputs freely, no aliases or `_v2` |
| suffixes — unless the maintainer says `check backward compatibility`. |
| **Fork nodes are different: anything under `forks/` keeps full back-compat |
| discipline by default** (never rename a fork ID in saved workflows, version |
| via new suffix/namespace, keep the `__koolook_vX_Y_Z` collision suffix). See |
| [`docs/maintainers/node-versioning.md`](../docs/maintainers/node-versioning.md) |
| and [`CLAUDE.md`](../CLAUDE.md) → *Change management*. |
| - **Third-party code stays out of MAIN.** Modified fork code lives under |
| `forks/<name>/versions/<vX_Y_Z>/`; raw upstream checkouts live in |
| `../ComfyUI-Forks/`. See [`forks/README.md`](../forks/README.md) and |
| [`forks/THIRD_PARTY.md`](../forks/THIRD_PARTY.md). |
| - **`dev-sync` is user-triggered only.** Never run it automatically (e.g. |
| after a commit, after a merge, on session end). The maintainer runs |
| parallel worktrees and an unsolicited sync overwrites whatever they're |
| reviewing in their live ComfyUI. Wait for the explicit phrase. Full rules |
| in [`CLAUDE.md`](../CLAUDE.md). |
| - **UI work needs visual QA.** See [`AGENTS.md`](../AGENTS.md) — open the |
| changed page in a browser, take a screenshot, verify before claiming done. |
| - **Three independent version axes** (pack version / fork wrapper version / |
| upstream pinned commit) — see [`docs/reference/versioning.md`](../docs/reference/versioning.md) |
| before any version bump. |
|
|
| ## Where to look next |
|
|
| - [`CLAUDE.md`](../CLAUDE.md) — full project conventions and protocols |
| - [`docs/maintainers/`](../docs/maintainers/) — release procedure, dev-sync |
| loop, registry API, sidebar starter preset, workflows-sidebar reference |
| - [`docs/reference/`](../docs/reference/) — glossary, versioning model |
| - [`docs/user_guide/`](../docs/user_guide/) — per-node end-user docs |
| - [`README.md`](../README.md) — public landing page + install |
| - [`CHANGELOG.md`](../CHANGELOG.md) — what changed, in detail |
|
|
