AGENTS.md

Agent Guide

This repo is the ComfyGit Manager custom node and panel UI for ComfyUI. It is not the cloud dashboard and it is not the core ComfyGit library. Most durable environment behavior belongs in the sibling comfygit repo; this repo owns the ComfyUI extension surface, local manager API, panel UX, and local development container for the manager.

Truth Layer

This repo has moved away from bead-first development. Do not treat .beads/ as the source of truth for product behavior.

Use the spec-driven truth layer under docs/:

• docs/spec-driven-development.md explains the local methodology.
• docs/contracts/README.md defines clause statuses and validation classes.
• docs/contracts/manager-ui/CONTRACT.md covers manager frontend guarantees.
• docs/contracts/manager-api/CONTRACT.md covers local HTTP API guarantees.
• docs/specs/ holds lifecycle and interaction specs.
• docs/architecture/service-boundaries.md explains manager/core/cloud responsibility boundaries.

When changing behavior covered by the truth layer:

1. Read the relevant contract/spec clauses before editing code.
2. Update docs when behavior or direction changes.
3. Use clause IDs in commit messages, PR notes, or validation notes when a change is intended to satisfy or modify a clause.
4. Do not mark clauses [LIVE] unless they are true in the current codebase.
5. Prefer explicit [PARTIAL] clauses over aspirational prose when the code only partly satisfies the desired behavior.

Useful validator from the spec skill:

python3 <spec-workflows-skill-dir>/scripts/validate_contract_docs.py docs

Codebase Map

Core frontend:

• frontend/src/main.ts registers the ComfyUI extension and mounts panel, modal, popover, and graph-adjacent UI.
• frontend/src/components/ComfyGitPanel.vue is the root panel shell and navigation coordinator.
• frontend/src/components/*Section.vue files are the main panel surfaces.
• frontend/src/components/WorkflowContractModal.vue and frontend/src/components/WorkflowIOMappingOverlay.vue are the contract authoring surfaces.
• frontend/src/composables/useComfyGitService.ts is the main API client.
• frontend/src/composables/useCloudAuth.ts owns local cloud auth state.
• frontend/src/types/comfygit.ts is the central frontend API type file.
• frontend/src/constants/ should hold user-facing strings/links that need to be easy to update.

Built frontend output:

• js/comfygit-panel.js and js/comfygit-panel.css are generated by cd frontend && npm run build.
• If frontend source changes affect the shipped panel, rebuild and include the generated js/ output unless the task explicitly says not to.
• js/comfygit-manager.js is a ComfyUI-side manager integration script, not the Vite bundle.

Backend/API:

• server/comfygit_panel.py registers the local /v2/comfygit/... panel API.
• server/comfygit_server.py registers ComfyUI Manager compatibility routes and feature flags.
• server/api/v2/ contains the domain route modules used by the panel API.
• server/cgm_core/ contains backend decorators, context helpers, serializers, and version utilities.
• server/cgm_utils/ contains small backend utility helpers.
• server/orchestrator.py supervises managed ComfyUI environment startup, restart, and switch behavior.
• server/workflow_file_watcher.py watches workflow files for panel refresh.

Docs and maps:

• docs/frontend-map.md and docs/server-map.md are orientation docs. Update them when major files move or responsibility boundaries change.
• docs/COMFYUI_MANAGER_ARCHITECTURE.md and docs/COMFYUI_MANAGER_UI_INTEGRATION.md are older but still useful reference material for ComfyUI integration details.

Tests:

• testing/unit/ covers backend units and orchestrator behavior.
• testing/integration/ covers integration behavior.
• testing/integration/panel/ protects the local panel HTTP contract.
• testing/run_tests.sh is the test helper entrypoint.
• Root package.json is for Playwright e2e support.
• frontend/package.json is for Vite/Vitest frontend work.

Local Dev Environment

Prefer the manager-owned scripts. See scripts/README.md and dev/docker/README.md for details.

Recommended Docker flow:

./scripts/setup-dev-env comfygit-cloud-test1 \
  --workspace <path-to-comfygit-workspace> \
  --docker \
  --comfyui-port 8189 \
  --torch-backend cu126

Direct lower-level Docker wrapper:

./scripts/start-dev-container comfygit-cloud-test1 --comfyui-port 8189

Behavior to know:

• If the named environment already exists in the workspace, the scripts reuse it.
• If it does not exist and --docker is used, the container entrypoint creates it.
• The dev container mounts this repo, the sibling comfygit repo, and the ComfyGit workspace.
• comfygit-core and comfygit-studio local editable paths are configured through .cec/overlays/.local.toml.
• Do not rely on direct uv pip install -e mutations inside an environment venv for persistent dev setup; cg sync and cg run own that venv.
• Docker Compose is configured with gpus: all. If GPU behavior fails, check nvidia-smi inside the container and the selected COMFYGIT_TORCH_BACKEND.

Browser-facing local URLs may need the dev machine Tailscale address rather than localhost when the user is on another machine. Check the global Codex machine context for current Tailscale details.

Python Environment Management

• ALWAYS use uv and the commands below for python environment management!
• NEVER try to run the system python!
• uv commands should be run in the root repo directory in order to use the repo's .venv

Common Commands

Frontend:

cd frontend
npm run build
npm run test:run

Backend tests:

cd testing
uv run pytest
uv run pytest integration/panel

Backend tests that need unreleased local comfygit-core or comfygit-studio changes:

./scripts/test-local-core
./scripts/test-local-core testing/unit/test_readiness.py -q

Run that script from the manager repo root. It keeps pyproject.toml pinned to the released ComfyGit packages, but runs the repo-local testing project with editable sources for sibling local core and Studio runtime checkouts. By default it expects the monorepo at ../comfygit; set COMFYGIT_CORE_PATH=/path/to/comfygit/packages/core and COMFYGIT_STUDIO_PATH=/path/to/comfygit/packages/studio-runtime when using a different checkout location. Use this for cross-repo development where manager code intentionally depends on local ComfyGit changes that have not been released to PyPI yet.

Script checks:

bash -n scripts/setup-dev-env
bash -n scripts/start-dev-container
bash -n dev/docker/start-stack.sh
docker compose -f dev/docker/docker-compose.yml config

Frontend version check:

./scripts/check-frontend-version.sh

Development Rules

• Preserve user work. This repo may have dirty generated assets or local harness changes; inspect diffs before staging or reverting.
• Do not commit broad generated bundle churn unless it corresponds to a frontend source change that needs to ship.
• Keep manager/cloud boundaries clear. The local panel may support auth, linking, and publishing, but full deployment, target/provider management, build artifacts, and runtime operations belong to the cloud dashboard.
• Keep durable environment and workflow contract persistence in comfygit-core where possible. The manager should route persistence through backend APIs and core helpers rather than directly editing durable state in the browser.
• When Manager consumes stable core-domain behavior, prefer typed core services and convert to JSON only at the manager API boundary. Do not duplicate core policy as ad hoc nested dictionaries in manager backend or frontend code.
• For user-facing constants, URLs, provider labels, and social links, prefer frontend/src/constants/ or a backend config surface over hardcoding strings deep inside components.
• The old beads workflow is no longer mandatory. If task records exist, use them as context only; truth-layer clauses and code/tests are the authoritative alignment mechanism.

Frontend Development

• Frontend source is in frontend/src/ (Vue 3 + TypeScript)
• Built assets go to js/ directory (committed to repo)
• cd frontend && npm run build - Rebuild frontend after changes
• cd frontend && npm run dev - Start dev server with hot reload
• IMPORTANT: Always rebuild frontend before committing if you changed:
  • Any file in frontend/src/
  • The version in pyproject.toml
• Version displayed in UI is injected from pyproject.toml at build time
• Pre-commit hook will block commits if frontend version doesn't match pyproject.toml
• Install hooks: ./scripts/install-hooks.sh

Dependencies

• Pin ComfyGit dependencies to exact versions - Always use ==X.Y.Z (not >=) for comfygit-core and comfygit-studio dependencies in pyproject.toml. This ensures reproducible builds and prevents unexpected breakage from core or Studio runtime updates.

Version Bump Protocol

Manager releases depend on the core/CLI monorepo release. The Manager package pins comfygit-core==X.Y.Z and comfygit-studio==X.Y.Z exactly, and ComfyUI registry installs consume requirements.txt, so the pinned core and Studio runtime versions must already exist on PyPI before publishing Manager.

When asked to prepare a Manager release:

1. Confirm the target comfygit-core==X.Y.Z and comfygit-studio==X.Y.Z have been published to PyPI. uv lock will fail, and registry installs will fail, if this is not true.
2. Bump comfygit-core==X.Y.Z and comfygit-studio==X.Y.Z in pyproject.toml dependencies.
3. Bump the Manager version in pyproject.toml.
4. Run uv run scripts/sync-requirements.py so requirements.txt matches pyproject.toml. Do not edit requirements.txt separately.
5. Run uv lock to update uv.lock against the published ComfyGit packages.
6. Run cd frontend && npm run build. The footer version shown in the bottom left of the ComfyGit panel is injected from pyproject.toml at build time, so the built js/comfygit-panel.js must be regenerated for the displayed version to change.
7. Run ./scripts/check-frontend-version.sh; it must report the same version in pyproject.toml and js/comfygit-panel.js.
8. Run targeted backend/frontend tests for the changed areas.
9. Stage pyproject.toml, uv.lock, requirements.txt, and generated js/ assets together, then commit.

After the release commit lands on main, the publish workflow creates the ComfyUI registry release and GitHub release. Do not publish Manager before the matching core and Studio runtime packages are available on PyPI.

For local development before core or Studio runtime is published, use editable ComfyGit overlays or the CI helper flow only for testing. Do not treat those local source overrides as a publishable Manager release state.

Additional Documentation

• frontend/THEMES.md - Theme system documentation

Commit Guidance

Use concise commit messages describing behavior. Include clause IDs when a change is directly tied to a truth-layer clause. Do not include obsolete bead IDs unless the user specifically asks for bead bookkeeping.

General

Don't make any implementation overly complex. This is a one-person dev MVP project. We are still pre-customer - any unnecessary fallbacks, unnecessary versioning, testing overkill should be avoided. Simple, elegant, maintainable code is the goal. We DONT want any legacy or backwards compatible code.

Cross-Platform Compatibility

This codebase must run on Windows, Linux, and macOS. All engineering choices should consider cross-platform compatibility:

• Use pathlib.Path instead of string concatenation for file paths
• Use os.path.join() or Path objects, never hardcode / or \\ separators
• Use shutil for file operations instead of shell commands when possible
• Avoid platform-specific shell commands; when unavoidable, handle all platforms explicitly
• Use subprocess with lists (not shell strings) to avoid shell escaping issues
• Be mindful of case sensitivity differences (Linux/macOS case-sensitive, Windows case-insensitive)
• Test path handling with spaces and special characters
• Use sys.executable for Python interpreter path, not hardcoded paths