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/rocksdanister/lively 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.

WAIT — Solo project — review before adopting

• Last commit 1w ago
• GPL-3.0 licensed
• ⚠ Solo or near-solo (1 contributor active in recent commits)
• ⚠ GPL-3.0 is copyleft — check downstream compatibility
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{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 rocksdanister/lively repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/rocksdanister/lively.

What it runs against: a local clone of rocksdanister/lively — 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 rocksdanister/lively | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch core-separation exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 40 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of rocksdanister/lively. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/rocksdanister/lively.git
#   cd lively
#
# 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 rocksdanister/lively and re-run."
  exit 2
fi

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

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

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

# 4. Critical files exist
test -f "src/Lively/Lively.Common/Com/IDesktopWallpaper.cs" \\
  && ok "src/Lively/Lively.Common/Com/IDesktopWallpaper.cs" \\
  || miss "missing critical file: src/Lively/Lively.Common/Com/IDesktopWallpaper.cs"
test -f "src/Lively/Lively.Common/Helpers/IPC/PipeClient.cs" \\
  && ok "src/Lively/Lively.Common/Helpers/IPC/PipeClient.cs" \\
  || miss "missing critical file: src/Lively/Lively.Common/Helpers/IPC/PipeClient.cs"
test -f "src/Lively/Lively.Common/Factories/IWallpaperLibraryFactory.cs" \\
  && ok "src/Lively/Lively.Common/Factories/IWallpaperLibraryFactory.cs" \\
  || miss "missing critical file: src/Lively/Lively.Common/Factories/IWallpaperLibraryFactory.cs"
test -f "src/Lively/Lively.Common/Helpers/LivelyPropertyUtil.cs" \\
  && ok "src/Lively/Lively.Common/Helpers/LivelyPropertyUtil.cs" \\
  || miss "missing critical file: src/Lively/Lively.Common/Helpers/LivelyPropertyUtil.cs"
test -f "src/Lively/Lively.Common/Services/IDialogService.cs" \\
  && ok "src/Lively/Lively.Common/Services/IDialogService.cs" \\
  || miss "missing critical file: src/Lively/Lively.Common/Services/IDialogService.cs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 40 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~10d)"
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/rocksdanister/lively"
  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).

Lively Wallpaper is a free, open-source Windows desktop application (built with WinUI 3) that sets animated wallpapers and screensavers from videos, GIFs, webpages, or full applications like Unity games. It solves the problem of static desktop backgrounds by enabling rich, interactive visual content while providing developer APIs for hardware telemetry, audio visualization, and music metadata injection into wallpapers. Monolithic structure: src/Lively/ contains core application; src/Lively/Lively.Common/ holds shared exceptions, COM interop, and utility extensions; src/Lively/Lively.Common.Services/ abstracts external concerns (GitHub updates, hardware usage via HardwareUsageService, audio via NAudioVisualizerService, now-playing via NpsmNowPlayingService). Schemas/ defines livelyPropertiesSchema.json for wallpaper property validation.

Windows users wanting animated desktop wallpapers without commercial software; wallpaper developers and content creators building interactive experiences using HTML/Webpage, Unity, or Godot; system integrators automating wallpaper control via CLI or scripts (AutoHotkey, Python); open-source contributors interested in desktop UI, interop, and media playback in C#.

Actively developed and moderately mature: project has 5.9k+ GitHub stars, 1.6M+ lines of C# code, CI/CD via GitHub Actions, and release artifacts on GitHub Releases. Desktop app is feature-complete with multi-monitor support, screensaver integration, and CLI controls. No major red flags visible, but wiki marked 'WIP' suggests docs may lag implementation.

Single-maintainer project (rocksdanister) creates bus-factor risk. Windows-only (WinUI 3 constraint) limits platform portability. Relies on system COM APIs (IDesktopWallpaper, ApplicationActivationManager) which may break across Windows updates. Dependency on WebView2 runtime and media codecs creates potential user-side installation friction. No visible test suite in file listing suggests coverage gaps.

Unable to determine from file listing alone (no git log, CHANGELOG, or open issues visible). README indicates active localization via Crowdin and mentions WIP documentation. GitHub Discussions and Reddit communities are active support channels.

git clone https://github.com/rocksdanister/lively.git
cd lively
dotnet restore
dotnet build

Requires .NET 6+ SDK and Visual Studio 2022 or JetBrains Rider. Open src/Lively.sln in IDE to debug WinUI 3 app.

Daily commands: Development: Open src/Lively.sln, Build → Build Solution, then Run (F5). Production: Download pre-built .exe installer from GitHub Releases, or build Release configuration and run setup via Inno Setup script.

• src/Lively/Lively.Common/Com/IDesktopWallpaper.cs — Core COM interface for Windows desktop wallpaper integration; all wallpaper rendering depends on this abstraction
• src/Lively/Lively.Common/Helpers/IPC/PipeClient.cs — Inter-process communication backbone; enables parent-child process coordination for wallpaper lifecycle management
• src/Lively/Lively.Common/Factories/IWallpaperLibraryFactory.cs — Factory for wallpaper library instantiation; critical abstraction for wallpaper discovery and instantiation patterns
• src/Lively/Lively.Common/Helpers/LivelyPropertyUtil.cs — Parses and manages wallpaper property schema; essential for custom wallpaper control bindings
• src/Lively/Lively.Common/Services/IDialogService.cs — UI dialog abstraction layer; defines contract for all user-facing dialogs across the application
• src/Lively/Lively.Common/Com/ApplicationActivationManager.cs — Windows app activation and lifecycle management via COM; required for proper wallpaper window spawning
• src/Lively/Lively.Common/Helpers/Storage/JsonStorage.cs — Persistent configuration and wallpaper state storage; all settings persistence flows through this layer

Add a new wallpaper property control (e.g., color picker, slider)

1. Define the new control in livelyPropertiesSchema.json with type and default value (schemas/livelyPropertiesSchema.json)
2. Update LivelyPropertyUtil to recognize and deserialize the new control type (src/Lively/Lively.Common/Helpers/LivelyPropertyUtil.cs)
3. In wallpaper runtime (WebView/Unity/etc), listen to IPC messages from PipeClient with the property value (src/Lively/Lively.Common/Helpers/IPC/PipeClient.cs)
4. Update LivelyControlModelConverter to handle JSON deserialization if custom control (src/Lively/Lively.Common/JsonConverters/LivelyControlModelConverter.cs)

Add a new external service integration (e.g., Spotify API, GPU monitor)

1. Create a new interface in src/Lively/Lively.Common/Services/ (e.g., ISpotifyService.cs) (src/Lively/Lively.Common/Services/IDialogService.cs)
2. Implement the service in src/Lively/Lively.Common.Services/ with network/hardware calls (src/Lively/Lively.Common.Services/GithubUpdaterService.cs)
3. Expose data to wallpapers via IPC messages; wallpapers receive updates via PipeClient (src/Lively/Lively.Common/Helpers/IPC/PipeClient.cs)
4. Register the service in dependency injection container (not visible in file list; typically in main app entry point) (src/Lively/Lively.Common.Services/Lively.Common.Services.csproj)

Add a new wallpaper type (e.g., Godot, Python renderer)

1. Create a new wallpaper library factory or extend WallpaperLibraryFactory for format detection (src/Lively/Lively.Common/Factories/WallpaperLibraryFactory.cs)
2. Update FileTypes.cs to recognize new wallpaper file extensions (src/Lively/Lively.Common/FileTypes.cs)
3. Implement a runtime process wrapper that spawns the Godot/Python executable and communicates via PipeClient (src/Lively/Lively.Common/Helpers/IPC/PipeClient.cs)
4. Handle platform-specific activation via ApplicationActivationManager if not standard Win32 (src/Lively/Lively.Common/Com/ApplicationActivationManager.cs)

Add a new application rule (e.g., pause on Zoom fullscreen)

1. Create or update application rules factory to detect Zoom process (src/Lively/Lively.Common/Factories/ApplicationsRulesFactory.cs)
2. Query active windows via DesktopUtil.cs to detect fullscreen Zoom window (src/Lively/Lively.Common/Helpers/Shell/DesktopUtil.cs)
3. Trigger pause command via PipeClient when condition met (src/Lively/Lively.Common/Helpers/IPC/PipeClient.cs)
4. Persist rule in JsonStorage so it survives app restart (src/Lively/Lively.Common/Helpers/Storage/JsonStorage.cs)

WebView2 Runtime: Users must have WebView2 runtime installed separately; missing it causes WallpaperWebView2NotFoundException and breaks HTML wallpapers. Media Codecs: Some video formats require Windows Media Feature Pack on N/KN SKUs; WallpaperPluginMediaCodecException signals this. COM Initialization: Desktop wallpaper control requires proper COM threading model; IDesktopWallpaper.SetWallpaper() may fail silently if called from wrong thread. Multi-monitor State: IDesktopWallpaper COM API does not support per-monitor wallpapers on Windows 10; design may conflict with multi-display setups. Screensaver Path: Screensaver integration requires registry modifications and .scr file registration; installer (Inno Setup) must handle this. .NET Runtime: Shipped app depends on .NET runtime; portable/self-contained build may not be generated in default config.

• Windows COM (Component Object Model) Interop — Lively uses COM to control the actual Windows desktop wallpaper (IDesktopWallpaper interface) and activate applications; understanding COM marshalling and threading models is essential for fixing wallpaper assignment bugs.
• Inter-Process Communication (IPC) via Named Pipes or CLI — Lively CLI automation (shown in README as command-line-controls feature) requires IPC for wallpaper control from external scripts; IpcMessageExtensions.cs encapsulates this pattern.
• Audio Visualization / Spectrum Analysis — NAudioVisualizerService extracts frequency-domain data from audio streams to drive music-reactive wallpaper effects; contributors adding audio features need signal processing fundamentals.
• Windows Registry Integration for Screensaver — Lively registers itself as a Windows screensaver (.scr) and modifies HKLM/HKCU registry keys; installation/uninstallation logic (Inno Setup) depends on registry state.
• Plugin Architecture / Provider Pattern — Lively abstracts wallpaper types (video, HTML, app) as pluggable providers; new wallpaper format support requires understanding plugin registration and lifecycle.
• WinUI 3 / Modern Windows UI Framework — Lively's UI is built with WinUI 3 (successor to UWP); contributors must understand XAML, dependency injection, and WinUI-specific threading models.
• JSON Schema Validation — livelyPropertiesSchema.json defines the contract for wallpaper interactive properties; understanding JSON-Schema is required for extending wallpaper capabilities.

• petpetgonggong/petpet — Alternative animated wallpaper engine using different rendering backend (Godot); comparable feature set but different tech stack.
• novasenco/Wallpaper-Engine — Commercial closed-source wallpaper tool that inspired much of Lively's feature design (video, interactivity, API); reference for what success looks like in this space.
• microsoft/winui-3 — WinUI 3 framework used by Lively for UI; understanding Microsoft's modern desktop tech stack is essential for contributors.
• naudio/NAudio — Audio processing library integrated in NAudioVisualizerService; contributors modifying audio features need NAudio API familiarity.
• MicrosoftEdge/WebView2Feedback — WebView2 runtime feedback/issues; wallpaper HTML rendering depends on this; critical for diagnosing webpage wallpaper failures.

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 Exception types in src/Lively/Lively.Common/Exceptions/

The repo has 8 custom exception classes (ScreenNotFoundException, WallpaperFileException, WallpaperNotAllowedException, etc.) but no visible test coverage. These are critical error handling paths for wallpaper operations. Adding unit tests would ensure exceptions are properly initialized, serialized, and provide meaningful error messages to users.

• [ ] Create src/Lively.Tests/Lively.Common/Exceptions/ directory
• [ ] Add test class for each exception type verifying constructor parameters and Message property
• [ ] Test exception serialization/deserialization for IPC scenarios
• [ ] Verify exception inheritance chain matches expected base types
• [ ] Add integration tests in ExceptionHandlingTests.cs to verify they're thrown correctly from Factory and Extension methods

Create GitHub Action workflow for C# code quality checks (StyleCop/SonarQube)

The repo lacks visible CI enforcement for code quality on pull requests. With a large .NET codebase spanning multiple projects (Lively.Common.Services, Lively.Common, etc.), implementing automated StyleCop analysis and optional SonarQube integration would catch naming convention violations, documentation gaps, and code smells before merge.

• [ ] Create .github/workflows/code-quality.yml with dotnet-format and StyleCop checks
• [ ] Configure .editorconfig file at repo root if missing to enforce C# conventions
• [ ] Add step to fail workflow if StyleCop violations are found
• [ ] Document in CONTRIBUTING.md the required code style and how to run checks locally
• [ ] Consider adding SonarQube analysis step for technical debt tracking

Document the IPC message contract schema in schemas/livelyPropertiesSchema.json and add validator utility

The repo has a schemas/ directory with livelyPropertiesSchema.json but lacks documentation on how plugins/wallpapers should use it. The IpcMessageExtensions.cs in Lively.Common/Extensions/ suggests IPC communication is critical. Creating a validator utility and documentation would help plugin developers validate their wallpaper property definitions before runtime.

• [ ] Create detailed README.md in schemas/ explaining livelyPropertiesSchema.json structure with examples
• [ ] Add IpcMessageValidator.cs utility class in src/Lively/Lively.Common/Helpers/ with JSON schema validation
• [ ] Create sample wallpaper property files (HTML, Unity, etc.) demonstrating valid schema usage
• [ ] Add unit tests for IpcMessageValidator covering valid/invalid schema scenarios
• [ ] Link schema documentation from CONTRIBUTING.md for plugin developers

• Add unit tests for src/Lively/Lively.Common/Extensions/ (EnumExtensions.cs, IpcMessageExtensions.cs, ProcessExtensions.cs) — these utility methods lack visible test coverage and are used across the codebase, making them high-impact targets.: Core utilities deserve regression tests; improves refactoring safety.
• Document the Lively Properties Schema (schemas/livelyPropertiesSchema.json) with annotated examples and JSON-Schema best practices — README mentions 'WIP' docs, and wallpaper developers need clear property contract definition.: Reduces friction for third-party wallpaper developers and closes 'WIP' documentation gap.
• Create integration tests for COM interop (src/Lively/Lively.Common/Com/) validating IDesktopWallpaper and IApplicationActivationManager behavior on target Windows versions — currently no visible test for OS integration layer.: Windows updates can silently break COM contracts; tests catch regressions early.

• High · Incomplete Dependency Analysis — src/Lively/Lively.Common.Services/*.csproj and src/Lively/Lively.Common/*.csproj. No package dependency file (package.json, packages.config, .csproj files content) was provided for analysis. This prevents identification of known vulnerabilities in third-party libraries such as NAudio, WebView2, or other NuGet packages used in the project. Fix: Provide package manifest files and implement automated dependency scanning using tools like OWASP Dependency-Check, Snyk, or GitHub's Dependabot to identify and remediate vulnerable dependencies.
• Medium · Potential Unsafe P/Invoke Usage — src/Lively/Lively.Common/Helpers/Pinvoke/NativeMethods.cs and DwmThumbnailWrapper.cs. The codebase contains P/Invoke calls (src/Lively/Lively.Common/Helpers/Pinvoke/NativeMethods.cs) which are inherently risky when dealing with unmanaged Windows APIs. Without code review, these could be vulnerable to buffer overflows, unsafe marshaling, or privilege escalation. Fix: Conduct thorough code review of all P/Invoke declarations. Use SafeHandle for native handles, validate all parameters, and ensure proper error handling. Consider using safer alternatives like Windows Runtime (WinRT) where possible.
• Medium · HTTP Download Functionality Without Visible Validation — src/Lively/Lively.Common.Services/HttpDownloadService.cs and GithubUpdaterService.cs. The presence of HttpDownloadService.cs and GithubUpdaterService.cs suggests automatic update functionality. Without visible integrity validation code, this could be vulnerable to MITM attacks or malicious updates. Fix: Implement cryptographic signature verification for all downloaded files. Use HTTPS with certificate pinning for critical downloads. Validate checksums and implement secure update mechanisms (e.g., using code signing certificates).
• Medium · IPC Communication Potential Injection Vector — src/Lively/Lively.Common/Helpers/IPC/PipeClient.cs and IpcMessageExtensions.cs. The IPC pipe client (src/Lively/Lively.Common/Helpers/IPC/PipeClient.cs) and IpcMessageExtensions suggest inter-process communication. Insufficient message validation could allow injection attacks. Fix: Implement strict message schema validation. Use serialization libraries with built-in security (protobuf, MessagePack). Avoid deserializing untrusted data without validation. Implement message signing/authentication for sensitive IPC operations.
• Medium · Archive Extraction Without Visible Validation — src/Lively/Lively.Common/Helpers/Archive/ZipExtract.cs. ZipExtract.cs functionality could be vulnerable to zip bomb attacks or path traversal exploits if extraction paths are not properly validated. Fix: Validate extracted file paths to prevent directory traversal attacks. Implement size limits to prevent zip bomb attacks. Validate file permissions before extraction.
• Low · Hardcoded Email Address for Security Reports — SECURITY.md. While not a vulnerability per se, publishing a personal email address (Awoo.git@gmail.com) in SECURITY.md without additional protection could expose it to spam or harvesting. Fix: Consider using a dedicated security contact email or a form-based vulnerability reporting system. Consider using GitHub Security Advisory feature for coordinated disclosure.
• Low · Missing Security Headers Configuration — General project structure - particularly relevant for HTML wallpaper support. For any web-based components or HTML wallpapers, there's no visible configuration for CSP, X-Frame-Options, or other security headers. Fix: Implement Content Security Policy and other security headers for any WebView2 content. Document security requirements for wallpaper creators.
• Low · Encryption Utility Requires Code Review — src/Lively/Lively.Common/Helpers/EncryptUtil.cs. The EncryptUtil.cs file suggests encryption functionality. Without seeing implementation details, proper key management and algorithm selection cannot be verified. Fix: Ensure use of modern cryptographic algorithms

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.