If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/LykosAI/StabilityMatrix shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 6d ago
• 5 active contributors
• Distributed ownership (top contributor 33% of recent commits)
• AGPL-3.0 licensed
• CI configured
• Tests present
• ⚠ AGPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live LykosAI/StabilityMatrix repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/LykosAI/StabilityMatrix.

What it runs against: a local clone of LykosAI/StabilityMatrix — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in LykosAI/StabilityMatrix | Confirms the artifact applies here, not a fork | | 2 | License is still AGPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 36 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of LykosAI/StabilityMatrix. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/LykosAI/StabilityMatrix.git
#   cd StabilityMatrix
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of LykosAI/StabilityMatrix and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "LykosAI/StabilityMatrix(\\.git)?\\b" \\
  && ok "origin remote is LykosAI/StabilityMatrix" \\
  || miss "origin remote is not LykosAI/StabilityMatrix (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(AGPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"AGPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is AGPL-3.0" \\
  || miss "license drift — was AGPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "StabilityMatrix.Avalonia/App.axaml.cs" \\
  && ok "StabilityMatrix.Avalonia/App.axaml.cs" \\
  || miss "missing critical file: StabilityMatrix.Avalonia/App.axaml.cs"
test -f "StabilityMatrix.Avalonia/App.axaml" \\
  && ok "StabilityMatrix.Avalonia/App.axaml" \\
  || miss "missing critical file: StabilityMatrix.Avalonia/App.axaml"
test -f "Directory.Build.props" \\
  && ok "Directory.Build.props" \\
  || miss "missing critical file: Directory.Build.props"
test -f "Directory.Packages.props" \\
  && ok "Directory.Packages.props" \\
  || miss "missing critical file: Directory.Packages.props"
test -f ".github/workflows/build.yml" \\
  && ok ".github/workflows/build.yml" \\
  || miss "missing critical file: .github/workflows/build.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 36 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~6d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/LykosAI/StabilityMatrix"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Stability Matrix is a cross-platform desktop package manager (Windows, Linux, macOS via Avalonia UI) that orchestrates multiple Stable Diffusion implementations (AUTOMATIC1111, ComfyUI, InvokeAI, Fooocus, Forge, etc.) through a unified interface. It handles installation, configuration, model management, and execution of diverse AI image generation backends without users managing Python environments or dependencies directly. C# monorepo using Avalonia for cross-platform UI (./Avalonia.Gif/), with .csharpierrc.yaml and .editorconfig enforcing code style. Build scripts in ./Build/ handle macOS app signing and notarization. GitHub Actions workflows automate builds across Windows, Linux, ARM64 macOS. Python integration via subprocess calls to launch backend CLIs. Custom Avalonia.Gif library handles animated image rendering in the UI.

AI/ML hobbyists and professionals who use multiple Stable Diffusion distributions but want a single launcher to manage different backends, switch between them, and avoid repetitive environment setup. Contributors are C# desktop developers, Python integration engineers, and Avalonia UI specialists.

Production-ready with active development: the project has CI/CD pipelines (build.yml, release.yml, version-bump.yml), Husky pre-commit hooks, Dependabot integration, and stable release/preview/dev version tracks published to cdn.lykos.ai. Latest stable badges and Discord community indicate active use. Codebase is 5M+ lines of C# with organized structure.

Moderate risk: tight coupling to 15+ external Stable Diffusion projects means breaking changes in upstream repos require rapid fixes; the manager depends on Python subprocess execution which can fail silently if environments corrupt. Single organization (LykosAI) maintains it, and managing 20+ distinct AI backends (each with different CLI interfaces) creates high integration surface area. No visible test-ui.yml results in repo data, suggesting UI test coverage may be limited.

Active release cycle with version-bump.yml automation, backport workflow for multi-version support, and stale issue management. Recent focus on macOS notarization (Build/notarize_macos.sh, Build/AppEntitlements.entitlements) and cross-platform CI improvements. Discord community indicates ongoing feature requests and backend integrations.

git clone https://github.com/LykosAI/StabilityMatrix.git
cd StabilityMatrix
dotnet restore
dotnet build
dotnet run --project StabilityMatrix.csproj

Requires .NET SDK (check .config/dotnet-tools.json for pinned version). macOS builds require Xcode; Windows requires Visual Studio 2022 or Build Tools.

Daily commands:

dotnet build -c Release
dotnet run --project StabilityMatrix --configuration Debug

For macOS code-signing: Build/codesign_macos.sh (requires Apple developer cert). Linux: direct AppImage generation via build.yml. Windows: portable ZIP or MSI. Dev iteration: dotnet watch run within the project folder.

• StabilityMatrix.Avalonia/App.axaml.cs — Application entry point and bootstrapping for the Avalonia-based UI framework; all initialization and dependency injection happens here.
• StabilityMatrix.Avalonia/App.axaml — XAML root configuration defining application-level resources, styles, and theme setup for the multi-platform UI.
• Directory.Build.props — Central MSBuild configuration defining SDK versions, target frameworks, and shared project settings across all 600 files.
• Directory.Packages.props — Centralized NuGet package version management ensuring consistent dependencies across all projects in the monorepo.
• .github/workflows/build.yml — CI/CD pipeline orchestrating builds for all supported platforms (Windows, macOS, Linux); defines release artifact generation.
• Runtimes.Default.props — Runtime-specific configuration for cross-platform Stable Diffusion integration, setting up platform-dependent executables and libraries.
• NuGet.Config — NuGet feed configuration ensuring correct package sources and authentication for build and runtime dependencies.

Add a new diagnostic/log feature

1. Create a new ViewModel inheriting from ViewModel in the LogViewer/Core/ViewModels directory (StabilityMatrix.Avalonia.Diagnostics/LogViewer/Core/ViewModels/ViewModel.cs)
2. Create corresponding XAML view in StabilityMatrix.Avalonia.Diagnostics/Views/ (StabilityMatrix.Avalonia.Diagnostics/Views/LogWindow.axaml)
3. Register the new log target or data store in LogDataStore.cs (StabilityMatrix.Avalonia.Diagnostics/LogViewer/Core/Logging/LogDataStore.cs)
4. Update ServicesExtension to inject new dependencies (StabilityMatrix.Avalonia.Diagnostics/LogViewer/Extensions/ServicesExtension.cs)

Add a new UI animation transition

1. Create new transition class inheriting from BaseTransitionInfo (StabilityMatrix.Avalonia/Animations/BaseTransitionInfo.cs)
2. Reference existing animation implementations as templates (StabilityMatrix.Avalonia/Animations/BetterDrillInNavigationTransition.cs)
3. Register transition in App.axaml resources (StabilityMatrix.Avalonia/App.axaml)

Support a new media format (e.g., APNG)

1. Create decoder class in Avalonia.Gif/Decoding/ following GifDecoder pattern (Avalonia.Gif/Decoding/GifDecoder.cs)
2. Create instance wrapper class (like WebpInstance.cs) (Avalonia.Gif/WebpInstance.cs)
3. Implement IGifInstance interface for format-agnostic frame handling (Avalonia.Gif/IGifInstance.cs)
4. Update GifImage.cs to instantiate new decoder based on file extension (Avalonia.Gif/GifImage.cs)

Add platform-specific runtime support

1. Define platform identifier and executable names (Runtimes.Default.props)
2. Update build script for new platform (.github/workflows/build.yml)
3. Add conditional symbols if needed (ConditionalSymbols.props)

• Avalonia — Cross-platform UI framework enabling single codebase for Windows, macOS, and Linux—critical for a multi-platform package manager.
• XAML + C# (WPF-like) — Familiar declarative UI pattern with code-behind for .NET developers; allows clean separation of UI and business logic.
• Custom GIF/WebP decoder (Avalonia.Gif) — Native Avalonia media controls lack GIF animation; custom decoder provides hardware-accelerated rendering without external dependencies.
• MSBuild + NuGet centralization — Monorepo with 600 files requires unified versioning and build configuration to prevent dependency conflicts and inconsistency.
• GitHub Actions CI/CD — Automates cross-platform builds and release distribution; integrates directly with Stability Matrix update delivery pipeline.
• Roslyn Analyzers — Enforces project-specific code conventions at compile time, improving consistency across large distributed team contributions.

• Custom GIF decoder instead of ffmpeg/native library

  • Why: Avoids runtime dependency bloat and platform-specific library distribution complexity.
  • Consequence: Higher maintenance burden; potential performance hit on large/complex GIF animations; but cleaner deployment on all platforms.

• Centralized NuGet versions (Directory.Packages.props) rather than per-project pinning

  • Why: Ensures all 600+ files use identical transitive dependency versions, preventing version mismatch bugs.
  • Consequence: Less flexibility for specialized projects; requires more careful version upgrade planning; but massively simplifies dependency hell in monorepo.

• Avalonia (XAML) vs. WinForms/WPF hybrid

  • Why: True cross-platform write-once-run-everywhere; WPF is Windows-only, WinForms even more limited.
  • Consequence: Learning curve for WPF developers; smaller ecosystem than WPF; but enables macOS/Linux support.

• In-process logging + LogDataStore vs. external log aggregation (e.g., Serilog + ELK)

  • Why: Stable Diffusion UI is desktop-only; no central log server needed; simpler deployment.
  • Consequence: No cross-device log aggregation; logs lost on app exit unless persisted to disk; but zero infrastructure overhead.

• Server-side API deployment — this is a desktop application package manager, not a backend service.
• Web-based UI — Avalonia desktop-first; no browser or web framework integration.
• Real-time model training orchestration — this is a package manager and launcher, not a training framework.
• Cross-platform binary compatibility without rebuild — each platform (win-x64, macos, linux) built separately.
• Plugin architecture with hot-reload — monolithic desktop app; no runtime extension system.

Python interop: Backend CLIs are launched as subprocesses; if Python environments corrupt or paths contain spaces, silent failures occur. macOS signing: Developer cert and provisioning profile required; codesign_macos.sh will fail without APPLE_SIGNING_IDENTITY env var. Upstream volatility: Each Stable Diffusion backend (AUTOMATIC1111, ComfyUI, Fooocus, etc.) has its own CLI interface; breaking changes upstream require immediate wrapper fixes. Cross-platform paths: Backslash vs. forward slash handling in subprocess commands differs between Windows/Unix; watch for hardcoded path separators. Dotnet version pinning: .config/dotnet-tools.json pins versions; newer .NET SDKs may not be backward-compatible. GIF memory: Custom Avalonia.Gif decoder loads full frames in memory; large animations can OOM on low-end systems.

• Subprocess Orchestration & CLI Wrapping — Stability Matrix's entire value proposition is launching and managing external Python CLI tools; understanding process lifecycle, stdio capture, and error handling is essential to all backend integrations
• LZW (Lempel–Ziv–Welch) Decompression — The custom Avalonia.Gif/Decoding/ module implements LZW decompression for GIF frame data; this is non-trivial and a source of bugs if not understood
• Cross-Platform Path Handling — Stability Matrix runs on Windows, Linux, and macOS with different path separators and conventions; subprocess CLI args must be escaped/quoted differently per OS to avoid silent failures
• MVVM (Model-View-ViewModel) UI Pattern — Avalonia uses MVVM architecture; understanding binding, data context, and command routing is required for any UI changes in this codebase
• Code Signing & Notarization (macOS) — Build/codesign_macos.sh and Build/notarize_macos.sh handle security entitlements; macOS Gatekeeper rejects improperly signed binaries, making this a release blocker
• CI/CD Pipeline as Code (GitHub Actions) — Multi-OS builds, automated versioning, and CDN upload are orchestrated via .github/workflows/; understanding matrix builds and artifact caching is key to release velocity
• Frame Disposal & GIF Animation States — Avalonia.Gif/Decoding/FrameDisposal.cs manages how previous frames are cleared between renders; incorrect disposal causes visual artifacts in animated previews

• comfyanonymous/ComfyUI — One of the primary Stable Diffusion backends Stability Matrix launches; understanding its CLI interface is essential for integration work
• AUTOMATIC1111/stable-diffusion-webui — The original AUTOMATIC1111 WebUI backend that Stability Matrix was likely designed to abstract over; baseline for understanding CLI wrapper patterns
• invoke-ai/InvokeAI — Another major composable Stable Diffusion backend managed by Stability Matrix; represents alternative architecture patterns
• lllyasviel/stable-diffusion-webui-forge — High-performance AUTOMATIC1111 fork; increasingly popular backend that Stability Matrix must keep in sync with
• AvaloniaUI/Avalonia — The cross-platform .NET UI framework powering Stability Matrix; critical for understanding desktop rendering and platform-specific quirks

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for Avalonia.Gif decoder components

The Avalonia.Gif directory contains critical image decoding logic (GifDecoder.cs, LzwDecompressionException.cs, GifFrame.cs, etc.) but there's no visible test project for these components. Given this is a media handling library in a UI application, robust tests for edge cases (malformed GIFs, LZW decompression failures, frame disposal logic) would prevent runtime crashes and improve reliability.

• [ ] Create StabilityMatrix.Tests project or add to existing test suite
• [ ] Add unit tests for GifDecoder.cs covering valid/invalid GIF streams
• [ ] Add tests for LZW decompression edge cases in Decoding/
• [ ] Add tests for FrameDisposal.cs enum logic and GifFrame.cs frame handling
• [ ] Add tests for WebpInstance.cs and animated webp support
• [ ] Integrate tests into test-ui.yml GitHub workflow

Add CI workflow for .NET code analyzer enforcement (StabilityMatrix.Analyzers)

The repo contains a StabilityMatrix.Analyzers.CodeFixes project but there's no dedicated CI workflow to enforce analyzer rules on PRs. Currently only test-ui.yml and build.yml exist. Adding analyzer validation in CI would prevent style regressions and catch issues early before merge.

• [ ] Create .github/workflows/code-analysis.yml workflow
• [ ] Add step to run dotnet analyzers (configured in .config/dotnet-tools.json)
• [ ] Configure to fail on warnings/errors from StabilityMatrix.Analyzers
• [ ] Add artifact upload for analyzer reports
• [ ] Document analyzer rules in CONTRIBUTING.md (reference .csharpierrc.yaml formatting rules)

Add integration tests for package manager core functionality in test-ui.yml

The repo's core purpose is a multi-platform package manager for Stable Diffusion, but test-ui.yml only references UI tests. Critical package manager operations (package installation, dependency resolution, platform-specific runtime selection via Runtimes.Default.props) lack visible automated test coverage. This is high-risk code that should be tested.

• [ ] Identify package manager core classes (likely in root StabilityMatrix project folder structure)
• [ ] Create StabilityMatrix.Core.Tests or extend existing tests
• [ ] Add tests for package metadata loading and version resolution
• [ ] Add tests for platform-specific runtime selection logic from Runtimes.Default.props
• [ ] Add tests for dependency graph validation before installation
• [ ] Integrate into test-ui.yml or create separate test workflow step

• Add unit tests for Avalonia.Gif/Decoding/GifDecoder.cs: currently no visible test coverage for LZW decompression logic and frame disposal handling, which are error-prone algorithms
• Document backend CLI integration patterns: create a CONTRIBUTING.md guide for adding new Stable Diffusion backends (e.g., how to wrap a new CLI tool like in Build/ scripts) since integration is the main extension point
• Implement cross-platform path validation in subprocess launcher: add tests and error handling for paths with spaces, special chars, and Unicode on Windows/Linux/macOS before spawning Python CLIs

The StabilityMatrix codebase shows moderate security posture. No critical vulnerabilities were identified in the visible structure, but several areas require attention: (1) Custom binary parsing in the GIF decoder needs security hardening, (2) Security configuration files are not visible and need verification, (3) Build automation scripts require injection attack protection, and (4) Complete dependency manifest review is needed. The project has good practices (Dependabot enabled, GitHub security workflows, code signing for macOS). Recommendations focus on auditing custom binary handling, ensuring build script safety, and completing security configuration review.

• Medium · Potential Insecure GIF Processing — Avalonia.Gif/Decoding/GifDecoder.cs, Avalonia.Gif/Decoding/GifFrame.cs. The Avalonia.Gif module includes custom GIF decoding logic (GifDecoder.cs) that processes binary data. Custom decoders can be vulnerable to buffer overflows, integer overflows, or DoS attacks if not properly validated. The presence of LzwDecompressionException suggests complex decompression logic that could be exploited. Fix: Audit the GIF decoder for buffer bounds checking, integer overflow protection, and resource limits. Consider using well-tested third-party libraries instead of custom binary parsing. Add fuzzing tests for malformed GIF inputs.
• Medium · Missing Security Headers Configuration — Project root and configuration directories. No visible security-related configuration files (like web.config with security headers, appsettings.json with security policies) were identified in the partial file structure. The application appears to be a desktop application but may have web service components that lack proper security headers (CSP, X-Frame-Options, etc.). Fix: Implement security headers in all web-facing components. For desktop apps, ensure API communications use HTTPS with certificate pinning. Document security configuration requirements.
• Low · Pre-commit Hook Configuration — .husky/pre-commit, .husky/task-runner.json. A .husky pre-commit hook exists (.husky/pre-commit) which could be modified to bypass security checks if a developer gains commit rights through compromise. The task-runner.json configuration should be reviewed for potentially dangerous tasks. Fix: Review and restrict permissions on .husky configuration files. Implement branch protection rules on main branches. Consider server-side hooks as the authoritative validation layer.
• Low · Build Script Security — Build/build_macos_app.sh, Build/codesign_macos.sh, Build/codesign_embedded_macos.sh, Build/notarize_macos.sh. Shell scripts in the Build directory (build_macos_app.sh, codesign_macos.sh, notarize_macos.sh) execute sensitive operations. These scripts could be vulnerable to injection attacks if they process untrusted input or use variables without proper quoting. Fix: Audit all shell scripts for proper input validation and variable quoting (use "$var" not $var). Use ShellCheck for static analysis. Restrict write access to these scripts. Consider using signed build scripts.
• Low · Dependency Management Visibility — Directory.Packages.props, NuGet.Config, .github/workflows/build.yml. The dependency file content was not provided in the analysis context. This prevents assessment of vulnerable packages, outdated libraries, or malicious dependencies that could be included. Fix: Provide complete dependency manifests for analysis. Implement automated dependency scanning in CI/CD (e.g., Dependabot is configured but status unknown). Regularly audit transitive dependencies.
• Low · Entitlements File Exposure — Build/AppEntitlements.entitlements, Build/EmbeddedEntitlements.entitlements. macOS entitlements files are present (Build/AppEntitlements.entitlements, Build/EmbeddedEntitlements.entitlements). These files should be reviewed to ensure they request only necessary permissions and don't grant excessive capabilities. Fix: Review entitlements to follow principle of least privilege. Only request permissions required for functionality. Regularly audit entitlements during security reviews.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.