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/t1m0thyj/WinDynamicDesktop 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 all four use cases

• Last commit 7w ago
• 2 active contributors
• MPL-2.0 licensed
• CI configured
• Tests present
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Single-maintainer risk — top contributor 81% of recent commits

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

What it runs against: a local clone of t1m0thyj/WinDynamicDesktop — 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 t1m0thyj/WinDynamicDesktop | Confirms the artifact applies here, not a fork | | 2 | License is still MPL-2.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 ≤ 78 days ago | Catches sudden abandonment since generation |

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(MPL-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MPL-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is MPL-2.0" \\
  || miss "license drift — was MPL-2.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 "src/Program.cs" \\
  && ok "src/Program.cs" \\
  || miss "missing critical file: src/Program.cs"
test -f "src/ThemeManager.cs" \\
  && ok "src/ThemeManager.cs" \\
  || miss "missing critical file: src/ThemeManager.cs"
test -f "src/EventScheduler.cs" \\
  && ok "src/EventScheduler.cs" \\
  || miss "missing critical file: src/EventScheduler.cs"
test -f "src/WallpaperApi.cs" \\
  && ok "src/WallpaperApi.cs" \\
  || miss "missing critical file: src/WallpaperApi.cs"
test -f "src/ThemeLoader.cs" \\
  && ok "src/ThemeLoader.cs" \\
  || miss "missing critical file: src/ThemeLoader.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 78 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~48d)"
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/t1m0thyj/WinDynamicDesktop"
  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).

WinDynamicDesktop is a Windows port of macOS Mojave's Dynamic Desktop feature that automatically cycles through a set of wallpaper images throughout the day based on a 24-hour schedule. It supports bundled macOS themes, custom user themes (.ddw format), and extensibility via PowerShell scripts, enabling time-synchronized desktop backgrounds on Windows 7-11. Desktop WinForms application in C# (src/ directory): core logic in AppContext.cs, dialog UI in Dialog.cs files, Windows COM interop in src/COM/ (ActiveDesktop.cs, DesktopWallpaper.cs), theme management via DefaultThemes.cs and ConfigMigrator.cs. Build system: WinDynamicDesktop.sln (Visual Studio solution). Installer/packaging: Inno Setup (scripts/installer.iss) and NuGet specs (scripts/windynamicdesktop.nuspec). Localization via Python scripts (scripts/i18n_.py) pulling from POEditor.

Windows users who want aesthetically synchronized desktop wallpapers that change throughout the day (like macOS), theme creators and maintainers who package wallpaper sets, and power users who want to extend functionality with custom PowerShell scripts.

Production-ready and actively maintained. The project has GitHub releases, Microsoft Store distribution (app ID 9NM8N7DQ3Z5F), Chocolatey and WinGet packages, and multiple distribution channels. CI/CD pipelines exist (.github/workflows/) with build, CodeQL analysis, and automated release workflows. Commit recency and issue responsiveness suggest active development.

Low-to-moderate risk: single primary maintainer (t1m0thyj) is a concentration risk, but the project has established distribution channels reducing catastrophic failure impact. Dependencies are minimal (Pillow, polib, requests for Python tooling only). The codebase is predominantly C# (295KB) with small Python/PowerShell scripts, limiting supply-chain risk. Desktop wallpaper APIs (Windows COM interop via src/COM/) are stable but OS-dependent.

Project maintains active CI/CD with GitHub Actions workflows for building, CodeQL security scanning, and automated releases to Chocolatey/WinGet. Version management via scripts/version.ps1 suggests structured release cycles. Internationalization pipeline exists (scripts/i18n_download.py) for community translations on POEditor.

Clone the repository: git clone https://github.com/t1m0thyj/WinDynamicDesktop.git. Open WinDynamicDesktop.sln in Visual Studio 2019+. For Python utility scripts, run pip install -r scripts/requirements.txt. Build the solution through Visual Studio IDE or via dotnet build if .NET CLI is configured.

Daily commands: Development: Open WinDynamicDesktop.sln in Visual Studio and press F5 to build and run. Release build: Right-click solution → Build Release. Installer: Run scripts/installer.iss through Inno Setup compiler or use iscc command-line tool. Python utilities (theme previews, localization): python scripts/make_previews.py or python scripts/i18n_download.py after installing pip install -r scripts/requirements.txt.

• src/Program.cs — Application entry point that initializes the main window, tray menu, and lifecycle management—every contributor must understand the startup sequence.
• src/ThemeManager.cs — Core orchestrator for theme loading, scheduling, and wallpaper application—handles the primary business logic of dynamic desktop switching.
• src/EventScheduler.cs — Manages the scheduling engine that triggers wallpaper updates at calculated times—critical to the dynamic behavior.
• src/WallpaperApi.cs — Abstracts Windows wallpaper-setting APIs (COM interop)—the bridge between application logic and OS integration.
• src/ThemeLoader.cs — Parses and validates theme JSON definitions, handling theme discovery and asset management.
• src/Localization.cs — Provides internationalization infrastructure used across the UI—required for multi-language support contributions.
• WinDynamicDesktop.sln — Visual Studio solution file defining project structure and build configuration—entry point for development environment setup.

Add a new scheduling strategy

1. Create a new scheduler class in src/ that extends or implements the scheduling interface (e.g., IScheduler pattern) (src/EventScheduler.cs)
2. Implement time calculation logic similar to SolarScheduler.cs (src/SolarScheduler.cs)
3. Register the new scheduler in ThemeManager's schedule selection logic (src/ThemeManager.cs)
4. Add UI option in ScheduleDialog to expose the new strategy (src/ScheduleDialog.cs)

Add support for a new theme source/provider

1. Extend ThemeLoader.cs to add a new discovery method (e.g., cloud API, custom repository) (src/ThemeLoader.cs)
2. Create a download/import handler similar to DownloadDialog.cs if remote fetching is needed (src/DownloadDialog.cs)
3. Update ThemeManager.cs to recognize and load themes from the new source (src/ThemeManager.cs)
4. Add configuration fields in JsonConfig.cs to persist the new provider settings (src/JsonConfig.cs)

Add a new language translation

1. Use i18n scripts to extract English strings (scripts/i18n_gettext.py)
2. Submit translations via POEditor or create a .po file (scripts/i18n_download.py)
3. Compile .po to .mo binary and place in src/locale/ (src/locale/de.mo)
4. Add language code to Localization.cs supported languages list (src/Localization.cs)

Extend wallpaper application to a new OS/display scenario

1. Examine current WallpaperApi.cs and DesktopHelper.cs for display enumeration (src/WallpaperApi.cs)
2. Add new COM interop interface in src/COM/ if needed (model after DesktopWallpaper.cs) (src/COM/DesktopWallpaper.cs)
3. Implement scenario-specific logic (e.g., UwpDesktop.cs handles UWP context) (src/UwpDesktop.cs)
4. Register scenario selector in ThemeManager or WallpaperApi (src/ThemeManager.cs)

• C# / .NET Framework (WinForms) — Direct Windows API access via COM interop; native Windows desktop integration; proven stability for system tray applications; cross-version Windows 10/11 compatibility.
• JSON configuration files — Human-readable theme definitions; portable across Windows machines; easy community contribution of new themes; avoids database dependency.
• SkiaSharp for image rendering — High-performance 2D graphics for theme preview generation; cross-platform rendering; GPU-accelerated if available.
• Gettext (.mo/.po files) for i18n — Standard translation ecosystem; POEditor integration for crowdsourced localization; ~30 languages supported; community-driven translations.
• COM interop (IDesktopWallpaper, IActiveDesktop) — Only reliable way to set desktop wallpaper on Windows; handles multiple monitors and virtual desktops; direct OS integration without external tools.

• WinForms over WPF/MAUI

  • Why: Simpler codebase; no XAML complexity; strong backward compatibility with older Windows versions; stable ecosystem.
  • Consequence: Less modern UI affordances; fewer declarative UI patterns; harder to implement complex animations.

• Local JSON themes instead of cloud database

  • Why: No backend infrastructure; offline-capable; users own
  • Consequence: undefined

COM threading: DesktopWallpaper.cs uses COM objects which require apartment-threaded marshalling—UI thread assumptions matter. PowerShell execution policy: Scripts may fail if system execution policy blocks unsigned scripts; see scripts/tools/chocolateyInstall.ps1 bypass. Windows version variations: WallpaperFit settings not persisted in Microsoft Store version (see README Known Issues); src/COM/ must handle OS-specific API differences between Win7-11. .ddw theme format: Custom theme parsing likely expects specific JSON structure—undocumented format, examine DefaultThemes.cs for structure. Full-screen app detection: src/FullScreenApi.cs hooks into OS state; timing issues on multi-monitor setups mentioned in issues.

• Windows COM (Component Object Model) Interop — WinDynamicDesktop directly invokes Windows COM objects (IDesktopWallpaper, IActiveDesktop) to manipulate desktop state—requires understanding apartment threading, marshalling, and P/Invoke patterns for OS API access
• 24-hour cyclic scheduling (modulo arithmetic for time-based events) — EventScheduler.cs maps wallpaper images to 24-hour timeline using time-of-day calculations; understanding periodic event scheduling is key to how images transition throughout the day
• WinForms event-driven UI architecture — Application uses WinForms (Designer.cs pattern) with event handlers for dialogs and background tasks; legacy but critical for understanding responsive UI without blocking main thread
• Theme manifest/metadata format (JSON serialization for .ddw) — Custom themes are .ddw files containing images and metadata; understanding how themes are parsed and validated is needed to support custom theme creation and validation
• PowerShell script execution in desktop applications — Application runs user-provided PowerShell scripts for extensibility (scripts/tools/); security and execution policy considerations are critical for sandbox/privilege escalation risks
• Application startup registry/autorun patterns — WinDynamicDesktop runs as background service with scheduled wallpaper changes; understanding system autorun, service registration, and background task scheduling in Windows is essential
• Localization via POEditor + gettext (i18n pipeline) — scripts/i18n_*.py automates translation crowdsourcing from POEditor; understanding .resx resource files and gettext workflow is needed for multi-language support

• telerik/UI-For-UWP — UWP alternative for modern Windows wallpaper applications; WinDynamicDesktop targets older WinForms but ecosystem moved to UWP
• nojesinternational/ChangeBG — Another Windows dynamic wallpaper solution with different scheduling approach; direct competitor solving same problem
• microsoft/terminal — Uses similar COM interop patterns and modern Windows API integration patterns for OS-level Windows features
• t1m0thyj/WDD-scripts — Official companion repo for PowerShell extension scripts shared by community; extends WinDynamicDesktop functionality
• apple/macos-dynamic-desktop — Original macOS Mojave Dynamic Desktop implementation that inspired this entire project

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 src/JsonConfig.cs and src/ConfigMigrator.cs

The repo handles configuration serialization and migration (JsonConfig.cs, ConfigMigrator.cs) but has no visible test files (.csproj with xUnit/NUnit). Configuration bugs can silently break user settings. Adding tests for config parsing, migration logic, and edge cases (missing files, corrupted JSON, version mismatches) would improve reliability and make future refactoring safer.

• [ ] Create WinDynamicDesktop.Tests.csproj with xUnit or NUnit framework
• [ ] Add tests/JsonConfigTests.cs covering serialization, deserialization, and invalid JSON handling
• [ ] Add tests/ConfigMigratorTests.cs covering version upgrade paths and fallback scenarios
• [ ] Update WinDynamicDesktop.sln to include test project
• [ ] Add test run step to .github/workflows/build.yml

Add GitHub Action workflow to validate translation files (i18n)

The repo has sophisticated i18n infrastructure (scripts/i18n_validate.py, scripts/i18n_gettext.py) for managing translations via poeditor, but no CI validation. New contributors could submit broken .po files or missing keys. A dedicated workflow would catch translation issues early, validate file format, check for missing required keys across all locales, and report coverage gaps.

• [ ] Create .github/workflows/i18n-validate.yml workflow file
• [ ] Configure workflow to run scripts/i18n_validate.py on PRs that modify translation files
• [ ] Add check to verify all required locale files exist and have matching key counts
• [ ] Output translation coverage report as workflow artifact
• [ ] Update CONTRIBUTING.md with i18n validation expectations

Add integration tests for src/DesktopHelper.cs and src/LockScreenChanger.cs COM interop

The repo directly interfaces with Windows COM APIs (DesktopWallpaper.cs, ActiveDesktop.cs, TaskbarProgress.cs) and applies wallpaper/lock screen changes through DesktopHelper.cs and LockScreenChanger.cs. These are Windows-specific and fragile—no visible tests exist. Adding integration tests (marked to run only on Windows CI) would catch regressions from Windows version updates and API changes, particularly important since this targets Windows 10 and 11.

• [ ] Create tests/DesktopHelperIntegrationTests.cs with [Collection("Windows Integration")] tests marked [WindowsOnly]
• [ ] Add tests for wallpaper application, verification, and error handling scenarios
• [ ] Create tests/LockScreenChangerIntegrationTests.cs covering lock screen image application
• [ ] Update .github/workflows/build.yml to conditionally run integration tests only on windows-latest runner
• [ ] Document in CONTRIBUTING.md that COM interop changes require manual Windows testing

• Add unit tests for src/ConfigMigrator.cs—handles configuration version upgrades but no test coverage visible in repo structure; could prevent migration regressions.: Medium: Core data migration logic with no tests is risky; good C# + file I/O practice
• Document .ddw theme format specification in CONTRIBUTING.md—theme creators exist but format is inferred from DefaultThemes.cs with no schema docs; add JSON example and validation rules.: Easy: Lowers barrier for community theme creation; improves discoverability
• Add PowerShell pre-flight checks to scripts/installer.iss—validate .NET Framework version and execution policy before installation; currently no visible validation logic.: Medium: Reduces installation failures and support burden; good integration testing practice

The WinDynamicDesktop codebase has

• High · Exposed API Keys in Environment Configuration — .env.example. The .env.example file contains placeholder API keys for LOCATIONIQ_API_KEY and POEDITOR_API_TOKEN. While these are examples, there is risk that developers may commit actual credentials to version control if .env files are not properly protected. The .env.example suggests these keys are used at runtime. Fix: Ensure .env files are in .gitignore, implement secret management via GitHub Secrets or environment variables, and use a secrets manager for production deployments. Never commit actual credentials.
• Medium · Third-party API Integration Without Visible Rate Limiting — src/LocationManager.cs, scripts/i18n_download.py, scripts/publish_choco.py. The codebase integrates with external APIs (LocationIQ, POEditor) based on the .env configuration. Without visible rate limiting mechanisms in the file structure, the application may be vulnerable to rate limit bypass or denial of service attacks. Fix: Implement rate limiting, exponential backoff, and circuit breaker patterns for external API calls. Add timeout configurations and request validation.
• Medium · Unvalidated External Theme Downloads — src/ThemeLoader.cs, src/DownloadDialog.cs, src/ThemeJsonValidator.cs. The ThemeLoader.cs and DownloadDialog.cs suggest downloading and loading themes from external sources. Without visible input validation or signature verification, this could lead to arbitrary code execution or malware installation. Fix: Implement cryptographic signature verification for downloaded themes, use HTTPS only, validate JSON schema strictly, and sandbox theme execution. Consider maintaining a whitelist of trusted theme sources.
• Medium · Python Script Dependencies Without Version Pinning — scripts/requirements.txt. The scripts/requirements.txt file lists Python dependencies (Pillow, poeditor, polib, python-dotenv, requests) without visible version constraints, allowing installation of vulnerable dependency versions. Fix: Pin all dependencies to specific, vetted versions using ==. Implement regular dependency scanning with tools like pip-audit or Safety. Use hash verification for PyPI packages.
• Medium · Potential Command Injection in PowerShell Scripts — scripts/package.ps1, scripts/tools/chocolateyInstall.ps1, scripts/version.ps1. PowerShell scripts (scripts/package.ps1, scripts/tools/chocolateyInstall.ps1) may be vulnerable to command injection if they construct commands from user input or external sources without proper escaping. Fix: Use parameter splatting instead of string concatenation, validate all inputs, avoid eval-like constructs (Invoke-Expression), and use -NoProfile -ExecutionPolicy Restricted when appropriate.
• Low · Insecure Deserialization Potential — src/JsonConfig.cs. The JsonConfig.cs file suggests JSON deserialization of user-provided configuration data. If not properly validated, this could lead to object injection attacks. Fix: Use strong type contracts for JSON deserialization, disable unsafe deserialization options, implement schema validation, and use JsonSerializerOptions with restrictive settings (IgnoreReadOnlyProperties = false, PropertyNameCaseInsensitive with caution).
• Low · Insufficient Logging Security Controls — src/LoggingHandler.cs. LoggingHandler.cs exists but visibility into what is logged is limited. API keys and sensitive data could be logged inadvertently. Fix: Implement log filtering to prevent sensitive data (API keys, tokens, personal information) from being logged. Use structured logging with appropriate log levels.
• Low · COM Interop Security Considerations — src/COM/ActiveDesktop.cs, src/COM/DesktopWallpaper.cs, src/COM/PowerSetting.cs, src/COM/TaskbarProgress.cs. The application uses COM interop for ActiveDesktop, DesktopWallpaper, and TaskbarProgress. COM objects can have security implications if not properly validated. Fix: Ensure proper error handling and validation of COM object calls, use try-catch blocks, validate return values, and document required Windows security context and permissions.

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.