Guide for AI Agents
This file provides guidance to agents when working with code in this repository.
#Non-Negotiable Behavioral Rules
- No co-authoring: Never add
Co-Authored-Bytrailers to any commit, PR body, issue comment, or PR review comment. Do not attribute AI assistance anywhere in git or GitHub output. - No
claude/branches: Never create or push a branch namedclaude/...(or after any AI tool), even when the session assigns one. Usechore/<slug>(the push skill's convention) or another descriptive prefix. - Commit as the owner: Author and commit as
Mooshieblob <[email protected]>. Set the repo-localgit config user.nameanduser.emailbefore the first commit; an AI author on a branch commit becomes aCo-authored-byline when GitHub squash-merges the PR.
#Error Logs
error-logs/directory: Drop large error logs, stack traces, or debug output here. Files in this directory are excluded from automatic context ingestion, so they won't consume live context tokens. Reference the filename when you need me to read a log on demand. This directory is git-ignored.
#Build & Run
npm install # Frontend dependencies
npm run tauri dev # Full dev (Tauri + Vite hot-reload on port 1420)
npm run tauri build # Production binary
cargo check # Rust compile check, desktop features (run in src-tauri/)
cargo check --no-default-features --features server # server binary build (run in src-tauri/)
cargo fmt # Rust format (run in src-tauri/)
cargo clippy # Rust lint (run in src-tauri/)Two Rust builds, one crate. default = ["desktop"] links tauri; the server binary (--no-default-features --features server, built by CI's build-server job) does not. A tauri reference outside a #[cfg(feature = "desktop")] gate compiles locally and breaks the release build. Modules gated whole in commands/mod.rs can use tauri freely; modules present in both builds (api.rs, video_export.rs, video_interpolate.rs, webserver.rs) need per-item gates, including on function parameters and the matching call-site arguments.
No frontend test framework. The frontend has no vitest/jest; a few pure-logic node:test files live in scripts/tests/ and the Guardrails workflow bundles them with esbuild and runs them. Rust does have tests: about 1,300 tests (#[test] + #[tokio::test]) in #[cfg(test)] modules over pure logic. Run cargo test --manifest-path src-tauri/Cargo.toml. The suite is green; treat any failure as a real regression.
#Critical Architecture (Non-Obvious)
Dual-mode app: Runs as Tauri desktop app AND as a browser-mode web app via embedded axum server (
src-tauri/src/webserver.rs). The flagwindow.__MOOSHIE_BROWSER_MODE__determines which mode is active.Custom IPC abstraction (
src/lib/utils/ipc.ts): ALL backend calls go throughipcInvoke()/ipcListen()— NEVER useinvoke()orlisten()directly. These route to Tauri IPC OR HTTP/SSE depending on the mode.Gallery storage: Gallery images are stored as PNG (the default), JPEG XL or WebP, per the output format setting. Display reads use
loadGalleryImageDisplay()(transcodes to WebP), PNG export usesloadGalleryImagePng(). Never read gallery files directly.Custom URI schemes: Tauri registers
thumbnail://andgallery://protocols for loading images from the gallery directory.MCP server (
src-tauri/src/mcp/,docs/MCP.md): opt-in, localhost-only, token-protected. It reuses the owner's last request per model (local txt2img, NovelAI txt2img, local Image Edit) and applies a few agent overrides. When adding or changing a feature, decide whether MCP has to follow: clear new per-imageGenerationParamsinputs insetups::snapshot, add assistant-controllable fields tosetups::Overridesand thegenerate_imageschema, consider a tool for new modes or gallery actions, and keep thecomfyui:*eventsmcp/jobs.rsfollows intact.
#Release Process Gotchas
- Version in 3 files must match exactly:
package.json,src-tauri/Cargo.toml,src-tauri/tauri.conf.json - Pre-commit hook is bash: hangs in PowerShell. Always use
git -c core.hooksPath=/dev/nullfor all git commands on Windows. - Tag protection: tags cannot be deleted or force-updated. Use
workflow_dispatchas fallback. - Full release procedure at
.github/prompts/release.prompt.md
#Other Non-Obvious Items
- CSP: A Content Security Policy is set in
src-tauri/tauri.conf.jsonand enforced in production builds only (there is nodevCsp, sonpm run tauri devnever exercises it). Any new remote<img>/fetchorigin or custom URI scheme must be added to it. - Ring buffer log capture: Both Rust (
src-tauri/src/log_buffer.rs) and frontend (src/lib/utils/log-buffer.ts) capture console output forexportLogs()diagnostics. - keep_alive config: When true, ComfyUI process survives app close. App kills ComfyUI on exit otherwise.
- Store files use
.svelte.tsextension — required for Svelte 5 rune compilation. - Agent config (canonical):
.agents/README.md- Skills:
push,release,quickrelease,cleanup,pre-commit-check,add-tauri-command,add-generation-param,add-comfyui-node,workflow-template-builder—.agents/skills/ - Rules: always-on + file-scoped —
.agents/rules/ - Claude Code mirror:
.claude/skills/,.claude/commands/(synced from.agents/)
- Skills:
- Existing AI rules:
GEMINI.md,.github/copilot-instructions.md,.github/instructions/(includingmooshieui.instructions.md),.github/agents/ - Project docs:
docs/README.md— bot triage, feature research, superpowers plans/specs