⌁ DESKO

Booting on a non-Windows machine gives you a working dashboard with Idle, Stats, Dev and Focus. The Music scene stays empty and the temperature widgets hide. Verbatim output of the degradation test:

sections after 6s with all Windows modules blocked:
  sys      {'cpuPercent': 21.8, 'ramPercent': 82.2, 'netDownKbs': 2869.5,
            'cpuTempC': None, 'gpuTempC': None, 'gpuPercent': None}
  media    ABSENT
  volume   ABSENT
  weather  {'tempC': 29.5, 'city': 'Bengaluru'}
  dev      {'source': 'git', 'branch': 'master', 'dirty': 16}
  focus    {'running': False}

[!NOTE] That test ran on Windows with the platform modules hidden. It proves the import guards and the degradation paths, not that Desko has been run on a real Mac. Nothing in the code is known to be Windows-path-dependent, but treat macOS as untested rather than supported.

What macOS parity would take, if you want it:

• Now playing. A nowplaying-cli style shim, or AppleScript against Music and Spotify. Apple's private MediaRemote framework has been progressively locked down for third-party processes, so the AppleScript route is the durable one.
• Volume. osascript -e 'set volume output volume N', as a small volume.py sibling.
• Temps. powermetrics needs root; iStats and smc are the usual third-party route.

The Dev scene needs nothing. desko/collectors/git.py shells out to git and the VS Code extension is plain JavaScript, so both already work anywhere.

1. Open the URL (or scan the QR with the phone camera).
2. Add to Home Screen via Chrome menu → Add to home screen. You get a fullscreen, chromeless app with a proper icon. Launch it from there, not from the browser.
3. Keep the screen on. Desko holds the display awake itself with a hidden always-playing video, the one trick that works over plain HTTP. For a permanently-mounted display, also enable Android's Stay awake:
   • Settings → About phone → tap Build number 7 times to unlock Developer options
   • Settings → System → Developer options → enable Stay awake
   • Keep it plugged in.

Desko's keep-awake falls back to a looping hidden video because the proper Screen Wake Lock API requires a secure context, and http:// on a LAN isn't one. Playing a video forever costs a decoder instance and real battery.

You can grant the exception, once, on the phone:

1. Open chrome://flags/#unsafely-treat-insecure-origin-as-secure
2. Set Enabled, and enter http://desko.local:7777 in the box
3. Relaunch Chrome

The bundled keep-awake shim feature-detects the native API and switches to it automatically, with no code change. The entry is a full origin including the port, and Chrome sometimes clears flags across major updates, so re-check it there if the screen starts sleeping again.

Android suspends timers and can drop a WiFi TCP connection without closing it. Desko detects both. An unanswered ping for 15 s forces a reconnect, and a gap of over 2 s in the render tick re-probes the link, so it recovers on its own within seconds. If it still stalls:

• Settings → Battery → App battery management → allow Chrome to run in the background. If you launched Desko from the home screen, that's a separate app entry, so set it there too.
• Turn off any WiFi power-saving toggle in the WiFi advanced settings.
• Enable the Wake Lock flag above, so keep-awake stops relying on the video fallback.

Install requirements-windows.txt for winsdk. Then just play audio in any app or browser tab on the PC. Windows' media session API sees Chrome, Edge, Brave, Spotify, and most desktop players. Nothing to configure per-app.

Lyrics resolve through a chain, first hit wins:

1. cache/lyrics/manual/<slug>.lrc, a file you dropped in yourself
2. LRCLIB exact match, retried across cleaned-up query variants
3. LRCLIB search, looser matching, still synced
4. lyrics.ovh, an independent catalogue, plain text only

Step 2's cleanup matters more than it sounds. Windows reports whatever the browser tab is called, so Channa Mereya (Official Video) [Lyrics] by Arijit Singh - Topic used to be a guaranteed miss. It now resolves. Results are cached including "no lyrics", so instrumentals aren't re-fetched every run, but a network failure is never cached as a miss.

To force lyrics for a specific song, drop an .lrc at cache/lyrics/manual/<artist>-<title>.lrc, lowercase, with non-alphanumerics collapsed to - (arijit-singh-channa-mereya.lrc). Bare <title>.lrc also matches, and .txt works for unsynced text. Manual files are read before the cache, so edits apply on the next track change with no restart.

Volume. The slider drives the PC's system master volume via pycaw, tracks changes you make on the PC, and the speaker button mutes. Without pycaw the control just hides.

CPU, RAM and network need nothing but psutil. Temps and GPU % need LibreHardwareMonitor, which this script installs for you:

pwsh -ExecutionPolicy Bypass -File scripts/setup-lhm.ps1

It puts LHM (portable) under %LOCALAPPDATA%\Desko\lhm and registers an elevated scheduled task Desko-LibreHardwareMonitor so it starts at login with the admin rights the sensors need. Desko also relaunches LHM itself whenever temps go offline by triggering that task, so there's no UAC prompt, and a closed or crashed LHM is back within about 20 s.

Re-running the script is safe. If LHM is already there it skips the download and just repairs the task. Without any of it, the temperature widgets simply hide.

The Dev scene has two independent data sources, so it keeps working whether or not your editor is open.

1. The VS Code extension (fast path). Copy it in:

Copy-Item -Recurse vscode-extension "$env:USERPROFILE\.vscode\extensions\desko-status-0.1.0"

# macOS / Linux
cp -r vscode-extension ~/.vscode/extensions/desko-status-0.1.0

Then reload the window (Ctrl/Cmd+Shift+P → Developer: Reload Window). It reports the workspace, branch, ahead/behind, the real changed-file list, the current file, cursor position and line ending, and the last commit.

It's event-driven, not polled. It subscribes to the git extension's state.onDidChange plus editor focus, selection and save events, so a branch switch reaches the phone in well under a second. Identical payloads are dropped rather than re-sent, and a 15 s heartbeat exists purely to prove the editor is alive. It also picks the repo that owns the file you're actually looking at, so multi-root workspaces resolve correctly.

2. The git collector (the floor). When the extension stops reporting for vscode_stale_sec (default 45 s), desko/collectors/git.py takes the section over and reads the repo directly. The chip in the panel header changes from ACTIVE to GIT, and the editor-only fields blank out rather than showing what happened to be open when you quit.

It follows whatever workspace VS Code last reported, so it needs no configuration. Open a folder once and Desko remembers which repo to watch. Set git_repo_path to pin it somewhere else. It also computes today's commits and lines changed, which rides along under either source.

If neither source has data, auto-rotation skips the Dev scene entirely rather than parking 60 s on an empty screen. A manual swipe still lands on it.

No setup at all. Open the Focus scene and press play. Work and break phases auto-flow, the lengths are adjustable from the scene itself or /config, and the timer lives on the server, so every connected device shows the same countdown and a page reload doesn't reset it.

Leave weather_city empty to auto-detect by IP, or set it explicitly ("Bengaluru, IN", "Berlin, DE"). Powered by Open-Meteo, free, no API key. Offline, the widget hides rather than showing stale numbers.

1. Write desko/collectors/disk.py. Every collector is one async def start(state, config, session) that loops forever:

"""Free disk space."""
import asyncio
import logging
import time

import psutil

log = logging.getLogger("desko.disk")


async def start(state, config, session) -> None:
    interval = float(config.get("poll", {}).get("disk_sec", 60))
    while True:
        try:
            u = psutil.disk_usage(config.get("disk_path") or "/")
            state.set_section("disk", {
                "freeGb": round(u.free / 1024 ** 3, 1),
                "pct": u.percent,
                "updatedAt": time.time(),
            })
        except Exception as e:                  # never let the loop die
            log.warning("disk read failed: %s", e)
            state.set_section("disk", None)     # None tells the scene to hide
        await asyncio.sleep(interval)

2. Declare the section in desko/state.py, in the _data dict: "disk": None. This is what a freshly connected phone receives in its snapshot.

3. Register the task in desko/server.py, inside on_startup:

tasks.append(asyncio.create_task(disk_mod.start(state, config, app["http_session"])))

4. Add the poll interval to DEFAULT_CONFIG in run.py and to config.example.json. load_config back-fills anything missing from the defaults, so nobody's existing config.json breaks when you add a key.

5. Route it to a scene in web/js/app.js: add disk: null to the state object, then send the section to whichever scene renders it, in mergeUpdate:

} else if (section === "sys" || section === "game" || section === "procs" || section === "disk") {
  if (scenes.stats && scenes.stats.onStateChange) try { scenes.stats.onStateChange(state); } catch (e) {}
}

Sections not listed there fall through to "notify the active scene", which is fine for data only one scene uses. The explicit branches exist so a section can update a scene that isn't on screen, which is what makes a scene correct the instant you swipe to it.

1. Never raise out of the loop. Nothing restarts a dead collector, and its section freezes at whatever it last published. Wrap the body, log a warning, keep sleeping.

2. Publish None when the source is gone. Every scene is written to hide a widget whose section is null. That single convention is the entire degradation strategy, and it's why the server boots fine on a Mac with half the collectors inert.

3. Import platform modules inside a guard, never at module top level. A bare import winsdk crashes the process on Linux before anything gets the chance to degrade gracefully. Copy the try/except header from media.py, volume.py or procs.py:

_HAS_ICONS = False
try:
    import win32gui
    from PIL import Image
    _HAS_ICONS = True
except Exception:
    pass

4. Use patch_section for chatty little fields. set_section broadcasts the whole section. The media collector updates the playhead 3x a second, and re-sending the base64 album art each time would saturate the link, so it patches just {"position": ...}. Both sides merge partials, so omitted fields survive.

5. Anything that blocks needs its own thread. The event loop also serves the WebSocket, the media position patches and the lyric timing, so a synchronous stall is visible on the phone as a stutter. The threshold in practice is a few milliseconds. Measured on a 367-process box:

Anything touching COM or WinRT needs a thread regardless of speed, because those APIs are apartment-bound. media.py, sysstats.py, volume.py and procs.py each own one. The pattern is always the same: the thread writes into a shared dict, and a cheap async loop publishes from it. procs.py is the shortest copy-paste template.

There is no scene auto-registration, so a new scene has to be listed in five spots. Miss one and you get a specific, diagnosable failure, listed here so you don't have to bisect it:

The module itself is an object on the Desko.scenes namespace, no imports and no exports:

Desko.scenes.x = (function () {
  var E = {};
  return {
    onEnter: function (state) { E.foo = document.getElementById("x-foo"); render(state); },
    onStateChange: function (state) { render(state); },
    onTick: function (state, nowMs) {},
    onExit: function () {},
  };
})();

onTick exists because the server never pushes a clock. Sending a time update every second to keep a countdown moving would be pure waste, so scenes interpolate locally and the socket stays quiet. onExit matters more than it looks: the stats scene closes its process popup there, because otherwise a rotation leaves the popup floating over the Music scene.

If your scene can be empty, teach _scene_available() in context.py to skip it. Auto-rotation consults it, a deliberate swipe does not, because "show me the thing I asked for, even if it's empty" is the right answer to an explicit request. The Dev scene is the worked example.

WebSocket for anything the server should remember, by adding a branch to _handle_client_msg in server.py. perf is the smallest possible example, all of three lines:

elif t == "perf":
    state.perf_mode = bool(msg.get("on"))

Note it sets a plain attribute, not a section. perf_mode and dev_seen_at are deliberately kept off the broadcast state because they're inputs to the server, not things any client needs told, and putting them in _data would push an update to the phone every heartbeat to announce that nothing changed.

An HTTP route for fire-and-forget actions, especially ones something other than the dashboard might call. POST /api/vscode is one; the extension is a separate process.

The one hard rule: never call COM from the event loop. A control that drives a threaded collector pushes onto a queue.Queue and lets the owning thread pop it. state.request_media_command and state.request_volume are the two existing examples, and both return immediately:

def request_volume(self, command: str) -> None:
    if not (command == "mute" or command.startswith("set:")):
        return                                  # validate here, not on the thread
    try:
        self.volume_commands.put_nowait(command)
    except Exception:
        pass

The target device is an old Chromium on a budget phone, and every constraint below is load-bearing rather than stylistic:

• var and function expressions. There is currently not a single arrow function, let or const in web/js/. Match that.
• No modules, no bundler, no build step, no CDN. Plain <script> tags attaching to one global Desko namespace. Everything is served off the LAN, so the dashboard works with the internet down.
• No new frontend dependencies. If you need a library, you probably need less feature.
• Every expensive effect needs a html.perf counterpart. Blur, glow, shadow transitions and infinite animations must all collapse to something flat under performance mode. style.css ends with a PERF MODE section (7 numbered groups, from line ~520) that strips each class of cost and says why it was worth stripping. Add yours there, then verify with ?perf=1.
• Use the CSS custom properties in :root (--primary, --muted-foreground, --border, --accent, --bad). No hardcoded hex.
• Design for 1520x720 landscape. That's the realme 3 this was built for. It's the floor, not a suggestion.

Measure before you argue with any of this: ?fps=1 puts a live frame-time readout on screen. Watch the max figure while lyrics are scrolling, since that's where a regression shows, not in the average.

The first run triggers a Windows Firewall prompt. Allow Python on Private networks. If you dismissed it, re-run and allow it, or add the rule manually. Confirm both devices are on the same WiFi, not one on 2.4 GHz guest and one on 5 GHz main.

That's the router's DHCP lease. Use http://desko.local:7777, which follows the IP automatically. If the phone is too old for mDNS (Android 10/11), add a DHCP reservation for the PC's MAC in the router admin page. Desko prints the MAC under the QR at startup.

Chrome tried HTTPS. Type the full http://desko.local:7777 including the scheme. On Android 10/11 there's no .local resolver at all, so use the numeric IP.

Play audio in an app or tab on the PC, not on the phone, and make sure requirements-windows.txt is installed (winsdk). Not available on macOS or Linux, see Platform support.

LibreHardwareMonitor isn't running, or isn't elevated. Run scripts/setup-lhm.ps1 once. Desko relinks within about 20 s once LHM is up, with no restart needed.

Not every track exists in LRCLIB or lyrics.ovh, and some only have unsynced text. Desko falls back to plain, then to an art-only card. If you want a specific song fixed for good, drop an .lrc into cache/lyrics/manual/, see the Music section above.

The extension isn't reporting. Check it's installed in the right folder for your editor (.vscode-insiders/extensions for Insiders), reload the window, and run Desko: Ping now from the command palette to force a report. If the scene says OFFLINE instead, there's no repo to fall back to either, so set git_repo_path in config.json, or open a git workspace in VS Code once so Desko learns the path.

Keep-awake needs one tap on the page to arm, because browser autoplay policy won't let it start the hidden video without a gesture. Tap once after loading. For a permanent display, enable Android's Stay awake as a backstop, or grant the Wake Lock flag described in Phone setup.

Tap the ⚡ bolt for performance mode. Add ?fps=1 to the URL to see whether it actually helped.

MIT explicitly grants the right to sell the software, which is the opposite of the intent here. So do Apache-2.0 and BSD. Creative Commons has a noncommercial variant, but Creative Commons themselves recommend against using CC licenses for software, and their "NonCommercial" wording is famously ambiguous at the edges.

What's in LICENSE instead is a short, plain-English noncommercial license: every noncommercial use stays wide open (personal, hobby, study, charity, education, public research, government), while commercial use is reserved to the copyright holder and available by asking.

Two trade-offs worth knowing:

• Because it restricts a field of use, this is not "open source" as the OSI defines the term. Some package registries, Linux distros and corporate policies exclude such licenses on principle. In exchange, nobody can take Desko, close it up and sell it.
• It grants copyright rights only. No patent license is granted, and the No Other Rights section makes that explicit by stating that these terms imply no other licenses.

The warranty disclaimer is not optional boilerplate. The No Liability section is this license's equivalent of MIT's AS IS block, and it's the one paragraph that protects the author rather than the user. It disclaims implied warranties (merchantability, fitness for a particular purpose) that some jurisdictions otherwise read into any supply of software, and it caps liability for damages. Desko launches LibreHardwareMonitor with administrator rights and reads hardware sensors, so that clause matters more here than it would for a static site.

Yes. Three facts that surprise most people:

1. Copyright is automatic. You own what you wrote the moment you wrote it. There's no form to file and no fee for the copyright itself to exist.
2. Public on GitHub does not mean free to use. With no LICENSE file, the default is all rights reserved. People may read your code but have no legal right to copy, modify or run it. The license is what changes that.
3. Adding one is the entire procedure. A text file in the repo root plus your name on the notice line. No lawyer, no registration, no paperwork.

Registration is a separate, optional thing. Some countries let you register a copyright with a government office for a fee, which mainly matters if you intend to sue for statutory damages. For a desk dashboard, skip it.