https://github.com/sharadcodes/deskpat
https://github.com/sharadcodes/deskpat
Last synced: 25 days ago
JSON representation
- Host: GitHub
- URL: https://github.com/sharadcodes/deskpat
- Owner: sharadcodes
- Created: 2026-05-25T11:47:00.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-05-25T12:34:01.000Z (about 1 month ago)
- Last Synced: 2026-05-25T14:09:47.456Z (about 1 month ago)
- Language: Python
- Size: 3.13 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# ๐ป DESKPAT: Spanned Wallpaper & System Dashboard
Welcome to **DESKPAT** (derived from the Hindi word **เคชเค (Pat)**, meaning *screen, canvas, or backdrop*), a modular, spanned multi-monitor wallpaper generator and real-time developer status HUD. Turn your empty desktop workspace into an elegant, custom-rendered dashboard.
> [!NOTE]
> **OS Compatibility Support**:
> * **Windows**: Fully supported and tested.
> * **macOS & Linux**: Core telemetry queries, multi-monitor display calculations, and background setters are implemented but currently **untested/experimental**. If you run these platforms, feedback and pull requests are highly welcome!
---
## โจ Features
* ๐ **Display Spanning**: Dynamically queries monitor coordinates, resolutions, and scaling factors to compile a single unified wallpaper canvas spanning all screens.
* ๐ **Live Diagnostics**: Built-in telemetry sensors track system uptime, local IP address, RAM/CPU load, and custom registered variables.
* ๐ **Todo Checklist CLI**: Interactively append, complete, and clear tasks from your checklist directly using CLI commands.
* ๐จ **HTML/CSS Visual Templates**: Design and render layouts using modern web technologies (compiled via headless Puppeteer).
* ๐ **Scriptable Fetchers**: Execute custom scripts (Node.js, Python, PowerShell, or Bash) to pull dynamic external APIs (quotes, weather, RSS feeds) into your background.
---
## ๐ Project Structure
All core implementation files are stored in `deskpat_src/` to keep your root directory clean:
```text
deskpat/
โ
โโโ deskpat.bat / deskpat.ps1 # Root wrappers (launchers)
โโโ README.md # This guide
โโโ deskpat_promo.png # Promotional banner
โโโ deskpat_src/
โโโ deskpat.py # Python orchestrator & monitor engine
โโโ sensors.py # System telemetry sensor plugins
โโโ render.js # Puppeteer HTML screenshot render engine
โโโ config.json # Theme & default configurations
โโโ todo.json # Local tasks list database
โโโ data.json # Standardized API payload context
โโโ scripts/ # Custom fetchers folder
โ โโโ sadhguru.js # Dynamic quotes & feeds fetcher
โ โโโ template.js # Fetcher boilerplate template
โโโ templates/ # HTML layout templates
โโโ default/ # Glassmorphic full-stats dashboard
โโโ minimal/ # Joyful split layout (Checklist & Quotes)
```
---
## โก Quick Start & Setup
### 1. Prerequisites
Ensure you have the following installed on your computer:
* **Python 3.x** (with `pip` in your system `PATH`)
* **Node.js & npm** (with `node` in your system `PATH`)
### 2. Dependency Initialization
When you run the tool for the first time, it automatically installs any missing dependencies:
* **Python**: `Pillow` (PIL) library
* **Node.js**: `puppeteer` (headless compiler)
### 3. Running the Engine
To fetch the latest data, build the layout canvas, and set the Span desktop wallpaper, run the launcher for your shell:
```bash
# Using Batch (Windows CMD)
.\deskpat.bat
# Using PowerShell
.\deskpat.ps1
# Directly via Python
python deskpat_src/deskpat.py
```
---
## โฐ Pro-Tip: Automate Updates with Task Scheduler
To re-apply the generated wallpaper after Windows sign-in and keep system stats fresh, register two current-user tasks:
* `Deskpat-AtLogon` runs once after sign-in. The 30-second delay gives Windows time to initialize the monitor layout before Deskpat generates the spanned wallpaper.
* `Deskpat-Every15Min` refreshes the wallpaper every 15 minutes so uptime, RAM, todos, and fetched content stay current.
### On Windows (via PowerShell)
Run this command from the project root. Administrator PowerShell is not required for the current-user task:
```powershell
$taskName = "Deskpat-AtLogon"
$deskpat = "C:\SOFTWARES\deskpat\deskpat.ps1"
$action = New-ScheduledTaskAction `
-Execute "powershell.exe" `
-Argument "-NoProfile -ExecutionPolicy Bypass -WindowStyle Hidden -File `"$deskpat`"" `
-WorkingDirectory "C:\SOFTWARES\deskpat"
$trigger = New-ScheduledTaskTrigger -AtLogOn -User $env:USERNAME
$trigger.Delay = "PT30S"
$settings = New-ScheduledTaskSettingsSet `
-StartWhenAvailable `
-AllowStartIfOnBatteries `
-DontStopIfGoingOnBatteries
Register-ScheduledTask `
-TaskName $taskName `
-Action $action `
-Trigger $trigger `
-Settings $settings `
-Description "Run Deskpat wallpaper generator after user logon" `
-Force
```
Register the repeating refresh task:
```powershell
$taskName = "Deskpat-Every15Min"
$deskpat = "C:\SOFTWARES\deskpat\deskpat.ps1"
$action = New-ScheduledTaskAction `
-Execute "powershell.exe" `
-Argument "-NoProfile -ExecutionPolicy Bypass -WindowStyle Hidden -File `"$deskpat`"" `
-WorkingDirectory "C:\SOFTWARES\deskpat"
$trigger = New-ScheduledTaskTrigger `
-Once `
-At (Get-Date).AddMinutes(1) `
-RepetitionInterval (New-TimeSpan -Minutes 15) `
-RepetitionDuration (New-TimeSpan -Days 3650)
$settings = New-ScheduledTaskSettingsSet `
-StartWhenAvailable `
-AllowStartIfOnBatteries `
-DontStopIfGoingOnBatteries
Register-ScheduledTask `
-TaskName $taskName `
-Action $action `
-Trigger $trigger `
-Settings $settings `
-Description "Update Deskpat wallpaper every 15 minutes" `
-Force
```
The refresh interval is customizable. Change `New-TimeSpan -Minutes 15` to any interval you want, such as `New-TimeSpan -Minutes 5` or `New-TimeSpan -Minutes 30`. Shorter intervals work, but each run launches Puppeteer and rewrites the wallpaper, so 15 minutes is a practical default.
Verify the task without signing out:
```powershell
Start-ScheduledTask -TaskName "Deskpat-Every15Min"
Get-ScheduledTaskInfo -TaskName "Deskpat-Every15Min" |
Select-Object LastRunTime, LastTaskResult
schtasks /Query /TN Deskpat-Every15Min /FO LIST /V
```
`LastTaskResult` should be `0`, and `schtasks` should show `Repeat: Every: 0 Hour(s), 15 Minute(s)`. You can also confirm Windows is caching the correct spanned wallpaper dimensions:
```powershell
Add-Type -AssemblyName System.Drawing
$path = "$env:APPDATA\Microsoft\Windows\Themes\TranscodedWallpaper"
$img = [System.Drawing.Image]::FromFile($path)
try {
[pscustomobject]@{ Width = $img.Width; Height = $img.Height }
} finally {
$img.Dispose()
}
```
For a two-monitor layout, the cached dimensions should match the full virtual desktop canvas, not a single monitor. For example, a 2560x1440 primary plus a 1920x1080 secondary may produce a `4480x1440` spanned cache.
Remove the task if needed:
```powershell
Unregister-ScheduledTask -TaskName "Deskpat-AtLogon" -Confirm:$false
Unregister-ScheduledTask -TaskName "Deskpat-Every15Min" -Confirm:$false
```
### On macOS / Linux (via Cron)
Add a crontab entry to execute the orchestrator:
```bash
# Run crontab -e and append:
*/15 * * * * cd /path/to/deskpat && ./deskpat.bat >/dev/null 2>&1
```
---
## ๐ ๏ธ CLI Options
The orchestrator CLI accepts arguments to override default configurations:
| Option | Description |
| :--- | :--- |
| `--script ` | Run a custom data fetcher script from `scripts/` (e.g. `--script sadhguru.js`) |
| `--template ` | Render a specific layout template folder (e.g. `--template default`) |
| `--url ` | Fetch raw text or JSON data directly from a web URL (bypassing custom scripts) |
| `--select` | Interactively list and pick an available template in the console |
*Note: Any unrecognized arguments are automatically forwarded straight to your custom script (e.g. `deskpat --script my_script.py --city "Seattle"`).*
---
## ๐ Local Todo Subcommand
DESKPAT includes a built-in command-line task checklist manager. Running these commands will modify `todo.json`, and the changes will render on your desktop checklist instantly on the next background update:
| Command | Description |
| :--- | :--- |
| `deskpat todo list` | List all active checklist tasks |
| `deskpat todo add "Task"` | Add a new task to your checklist |
| `deskpat todo done ` | Toggle completion status of task `` (e.g. `deskpat todo done 1`) |
| `deskpat todo remove `| Remove task `` from the checklist |
| `deskpat todo clear` | Clear all tasks |
---
## ๐ Extensibility & Customization
### 1. Writing Custom Data Fetchers
You can drop scripts into `deskpat_src/scripts/`. Fetcher scripts can be written in **Node.js (`.js`)**, **Python (`.py`)**, **PowerShell (`.ps1`)**, or **Shell (`.sh`/`.bat`)**.
* **Requirement**: The script must output a clean JSON object to `stdout`.
* The orchestrator automatically executes your script, parses its output, and saves it into `data.json`.
### 2. Creating New Visual Layouts
Templates are stored under `deskpat_src/templates/`. To build your own:
1. Create a folder (e.g., `templates/custom-dashboard/`).
2. Add a `template.html` and `style.css`.
3. In `template.html`, read the global context `window.wallpaperData` in JavaScript to populate your fields.
4. Set it as default in `config.json` or call `deskpat --template custom-dashboard`.
### 3. Adding New Modular OS/System Sensors
OS-level metrics are queried via `deskpat_src/sensors.py`. To add a new system stat (e.g., free disk space, CPU temperature, or battery level):
1. Open `sensors.py` and write a Python function.
2. Register it using the `@sensor("metric_name")` decorator.
```python
@sensor("disk_free_gb")
def get_disk_free():
import shutil
total, used, free = shutil.disk_usage("/")
return round(free / (1024**3), 1)
```
This variable automatically loads into `data.json` and becomes instantly available inside your HTML templates in JavaScript at `window.wallpaperData.system.disk_free_gb`!