Skip to content

AGENTS.md

Latest commit

 

History

History
64 lines (42 loc) · 4 KB

AGENTS.md

File metadata and controls

64 lines (42 loc) · 4 KB
Raw

AGENTS.md

Guide for LLM agents (Claude Code, Cursor, Copilot, etc.) working on this repository.

What it is

A PowerShell tool for Windows that sets James Webb Space Telescope photos as the desktop wallpaper, across one or more monitors. No external dependencies, no build step, no API key. Everything runs with the PowerShell included in Windows 10/11.

Code map

The project is deliberately minimal: two PowerShell scripts.

Set-SpaceWallpapers.ps1 — main script

Entry points (parameters): -GUI opens the chooser window; -Monitor <n> changes a single monitor (0-based index); no arguments changes all monitors.

Flow and key functions:

  • $dwCode — inline C# definition of the COM interface IDesktopWallpaper (GUID B92B56A9-...) and the static wrapper class DW. ⚠️ The method order in the interface must exactly match the COM vtable — do not reorder them. Loaded at runtime with Add-Type.
  • Get-EsawebbPool — scrapes esawebb.org: downloads the category pages and extracts image ids via the regex href="/images/([\w-]+)/", deduplicating and skipping non-image entries (archive, search, etc.).
  • Get-CommonsPool / Get-CommonsThumbUrl — Wikimedia Commons fallback via the api.php API.
  • Initialize-Pool — builds the pool only once: uses esawebb if it returns ≥10 images, otherwise Commons. State stored in $script:pool / $script:poolSource.
  • Get-PreparedImage — downloads an image, resizes it with System.Drawing if the longest side exceeds $maxDim (default 3840 px), saves it as JPEG.
  • Set-OneMonitor — picks a not-yet-used image, prepares it and sets it on the monitor via DW::Set. Tries up to 6 candidates before giving up.
  • Invoke-Switch — orchestrator: initializes the pool, loops over the monitor indices, sets the "Fit" position (DWPOS_FIT = 3) at the end.
  • Show-Chooser — Windows Forms GUI with radio buttons (All / individual monitors) and a "Change" button.

Install.ps1 — installer

Creates a "JWST Wallpapers" .lnk shortcut on the desktop (via the WScript.Shell COM object) that launches Set-SpaceWallpapers.ps1 -GUI with -ExecutionPolicy Bypass. Uses $PSScriptRoot to stay portable: it works from any folder.

Conventions

  • Language: comments, logs and the GUI are in English. Keep this convention.
  • Verb-Noun: functions follow the standard PowerShell naming (Get-, Set-, Invoke-, Initialize-, Show-).
  • Portability: do not hardcode absolute paths. Use $PSScriptRoot (or the $MyInvocation fallback) as the base; everything is relative to the script folder.
  • Logging: use the Write-Log function for every meaningful event; it writes to nasa-wallpaper.log and to stdout.
  • No external dependencies: PowerShell + system .NET assemblies only (System.Drawing, System.Windows.Forms). Do not introduce modules to install or API keys.

Generated / excluded files

Defined in .gitignore — do not commit them:

  • images/ — wallpapers downloaded at runtime (they regenerate by themselves).
  • *.log — execution logs.
  • esawebb-example.jpg — example image too heavy (~10 MB).

How to test changes

There are no automated tests. Manual verification on Windows with at least one monitor:

# Quick test without GUI: change monitor 0
.\Set-SpaceWallpapers.ps1 -Monitor 0
# Check the outcome in nasa-wallpaper.log

The script requires real Windows (the IDesktopWallpaper COM API and System.Windows.Forms): it does not run on Linux/macOS or in headless environments.

Important notes for changes

  • The esawebb.org scraping depends on the site's HTML structure: if the site changes, the regex in Get-EsawebbPool may break → in that case the Commons fallback kicks in.
  • Be respectful of the source sites: generous timeouts and a single UserAgent. Do not increase the request rate.
  • Images must never be redistributed in the repo (licensing matter): they are only downloaded by the user at runtime. See the credits in the README.