mold: Instructions file for Claude Code

CLAUDE.md

Guidance for Claude Code in this repository. AGENTS.md is a symlink to this file.

Only rules that apply to ANY change live here. Area-specific invariants live in path-scoped .claude/rules/*.md files, which load automatically when you read matching files — read the relevant one before editing an area it covers (e.g. inference.md, server-queue.md, studio-web.md, desktop.md, mesh-3d.md, gallery-authority.md, reference-images.md, chain-sequences.md, prompting-corpus.md, release-ci.md, ios-native.md). New area-specific rules go there, not here.

What mold is

Local AI image/video/3-D generation CLI built on candle: FLUX, SD1.5, SDXL, SD3.5, Z-Image, Flux.2 Klein/Dev, Qwen-Image, Qwen Image 2.1, Wuerstchen v2, LTX-Video, LTX-2, Wan 2.1/2.2, Hunyuan3D, MiniMax H3. Single binary, everything feature-gated. mold run talks to $MOLD_HOST (default http://localhost:7680) and falls back to the local GPU when the server is unreachable (auto-pulling the model); --local skips the server.

Commands

# Nix (preferred)
nix build                   # Build mold (default CUDA/Metal)
nix fmt                     # treefmt (nixfmt + rustfmt), configured inline in flake.nix; no rustfmt.toml
nix flake check             # CI-equivalent gate

# Local CI runner (what to run before a PR; devshell alias: ci-local)
./scripts/ci-local.sh [rust|web|docs|contracts|gpu|nix] [-k] [--list]

# Cargo — common loops
cargo check
cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --all -- --check
cargo nextest run --profile main --workspace   # full suite, what a push to main runs (cargo test --workspace is equivalent, slower)
cargo nextest run --profile pr $(python3 scripts/ci/affected-packages.py --base origin/main --head HEAD | sed -n 's/^packages=//p')   # what a PR runs (see .config/nextest.toml; add --features from the same script)
cargo test -p mold-ai-core --lib <filter>    # single test/module; use the PACKAGE name (table below), not the dir
cargo test -p mold-ai-server --features mdns --lib mdns   # feature-gated modules (mdns, pulid, h3) never compile under --workspace
cargo +1.93 check -p mold-ai --locked --features preview,discord,expand,metrics,webp,mp4,mdns,pulid   # MSRV gate (weekly msrv.yml, not on the merge path)
cargo check -p mold-ai --features cuda,preview,discord,expand,webp,mp4,metrics,mdns,pulid,mesh-texture,mesh-matting,mesh-delight   # the PR-route cuda-typecheck (needs nvcc); the h3 arm is covered by metal-check on macOS; a default-feature build type-checks none of the GPU cfg arms
./scripts/coverage.sh [--html]

# CI contracts
cargo run -p mold-ai-core --bin generate_prompting_guides -- --check
cargo run -p mold-ai-core --bin generate_generation_profiles -- --check
bash scripts/tests/ci-routing-contract.sh
bash scripts/tests/candle-single-identity.sh     # every candle crate on ONE fork rev

# Frontend (one Bun workspace at repo root; prettier scoped to studio/, desktop override in .prettierrc)
bun run check:frontend        # architecture check + tests + web/desktop builds
bun run check:architecture    # scripts/tests/frontend-architecture.sh
bun run check:dead-code       # knip
bun run fmt:check
bunx vitest run --config studio/vitest.config.ts studio/lib/<file>.test.ts   # single studio test
cd web && bunx vitest run src/<file>.test.ts                                 # single web test (desktop/ likewise)
cd desktop && bunx vitest run ../ui/<path>.test.ts                           # ui/ tests only run through desktop's vitest

# Local dev run (MUST prefix with ensure-web-dist so the embedded SPA isn't a stub)
./scripts/ensure-web-dist.sh && cargo run --profile dev-fast -p mold-ai \
  --features metal,preview,expand -- run "a cat"