A small Windows tray app, live Herdr dashboard, lightweight Windows system monitor, and media-session companion for the existing fail-closed Herdr night watcher.
The app controls the robust WSL background watcher; it does not replace it.
This repository contains the Rust tray app, the Python watcher, Windows scripts, tests, documentation, and a tested Windows executable.
We often let Herdr run overnight because Compound Engineering plans can become very large. Once such a plan starts, several agents may continue working autonomously for hours. The computer does not need to stay on all night, though: when all work is complete, Windows should reliably enter sleep mode or shut down.
That handoff between “Herdr is finished” and “Windows may go to sleep” was not reliably solved before. Herdr Night Watch closes that gap: it monitors the agents fail-closed, makes the current state visible, and performs the selected power action only after a configurable warning period. The same compact window is also a useful “what is my computer doing right now?” surface: it shows the Herdr workload, CPU/RAM/GPU/VRAM and GPU power telemetry, weather for a chosen place, and the music that Windows currently considers active.
The interface supports Deutsch and English. Change the language from the tray right-click menu under “Sprache / Language”. The live window also provides a compact system monitor for CPU, RAM, GPU, occupied VRAM, and NVIDIA GPU power use.
Herdr Night Watch is not tied to one coding agent. It works with Codex, Claude Code, or any other agent that Herdr can report. The only required integration is Herdr itself.
Codex and Claude Code do the work. Herdr is the shared terminal runtime that knows whether their agents are still working, waiting, or finished. Herdr Night Watch does not read prompts, source code, or terminal output. It only asks Herdr for the current agent states and uses that answer to decide whether Windows may sleep.
Codex / Claude Code / other coding agents
|
v
Herdr terminal runtime in WSL
|
v
herdr-night-watch.py checks agent states
|
+-- work remains -> keep watching
+-- status uncertain -> do nothing (fail-closed)
+-- all work complete -> visible warning period
|
v
Windows sleep or shutdown
Windows tray app = configuration, live status, start/stop, and cancellation
The tray app never launches, stops, or controls Codex or Claude Code. It only watches the state Herdr reports. This is why one Night Watch installation can support mixed Herdr sessions, for example Codex and Claude Code working in parallel.
Open Open setup from the tray right-click menu to set:
- the name of your WSL distribution, for example
Ubuntu; - the WSL path to
herdr-night-watch.py.
For a checkout of this repository, the path normally looks like /home/your-name/projects/herdr-night-watch/watcher/herdr-night-watch.py. The setup is stored locally in the Windows user registry and is never committed to Git.
- Windows with WSL installed;
- a WSL distribution with Python 3 and the Herdr CLI available;
- Codex, Claude Code, or another agent running inside Herdr when there is work to monitor;
- the Herdr Night Watch tray app running while a night run is active.
The live window is intentionally compact: Herdr counts and the night-mode controls remain in the main panel, while the equal-width footer turns it into a quick system monitor without affecting the watcher. CPU, RAM, GPU, VRAM utilization, and NVIDIA GPU power use a soft traffic-light palette: green for normal load, pastel yellow for medium load, and pastel red for high load. Missing hardware telemetry is shown as — rather than guessed. The small upper-right control hood opens the last 30 completion actions and cycles the window between normal, always-on-top, and always-in-background modes. Its glass surfaces use a subtle top reflection to keep the dashboard calm but tactile. The tray menu lets you choose window opacity from 100% down to 10%.
When Windows exposes an active media session, the footer shows the current artist and title in compact color-coded pills. Spotify is a supported example, as are Tidal and other players that publish playback through Windows' Global System Media Transport Controls. Night Watch does not log in to Spotify, call the Spotify API, read playlists, or access account data. Windows provides the currently active media metadata, and Night Watch reads only that local session snapshot.
The dotted timeline gives an immediate playback overview. Hovering previews the position that would be selected; clicking seeks there when the media session allows playback-position changes. The played dots transition softly from the artist color toward the title color, while the unplayed track remains subdued. This makes the current song readable at a glance without adding a full music player, album art, volume controls, or playback buttons. The media strip is informational and independent of the Herdr watcher: music can continue while Herdr works, and Herdr monitoring continues when no media session exists.
The moon also shows the current temperature and the real current lunar phase for the selected weather location. Open-Meteo supplies the daily phase value, so the icon shifts between crescent, quarter, gibbous, full, and new moon; the temperature stays centered, with a background-blue outline only on the lit sickle so the digits stay readable. Leipzig is used initially; the small weather control at the lower-right appears on hover and opens a searchable city selector. Weather and moon data are informational only, are refreshed in the background, and fall back to the last value or a local phase estimate when the network is unavailable.
- Start night mode: continuously monitors all agents currently reported by Herdr and only shuts down Windows after the configured quiet period.
- Prevent idle sleep while the tray runs: for its entire lifetime, the tray app tells Windows that the system is still required, even when night mode is off. The display may still turn off. The guard is released only when the tray app exits; deliberate sleep or shutdown actions by the user or watcher are still allowed.
- Observe only: runs the same monitoring flow without performing a shutdown.
- Stop and cancel shutdown: ends the run and removes only the watcher's own warning; Windows is not asked to shut down until the warning has completed.
- Demo: simulate completion: shows the quiet period and shutdown warning within a few seconds. It can never shut down Windows.
- Open live status: opens a freely movable status window that can be closed at any time. Left-clicking the tray icon opens it; right-clicking shows the menu.
- Reliable live window: opening the live status again restores and focuses the existing window instead of creating a duplicate. Its last desktop position is stored locally and reused after the next start.
- Proportional live-window scaling: drag the subtle handle in the lower-right corner to enlarge or shrink the complete live window freely. Text, moon, KPI cards, metrics, media pills, and timeline stay proportional. The selected scale is stored locally; right-click an empty area and choose Reset to 100% whenever you want to return to the default size.
- Finished-agent glow: when Herdr reports completed work, the finished count turns green with the previous warm yellow halo. The light contour around the digit stays one screen pixel thick, even when the live window is scaled up.
- Open live window at startup: double-clicking the app opens the live status window together with the tray. If the tray is already running, a second double-click just brings that window back. Windows logon can still skip the window if you turn the tray option off.
- Completion log: the live window's upper-right log button opens a read-only view of the last 30 requested sleep and shutdown actions plus detected unclean tray exits. An unclean exit is recorded when the tray starts again without finding a clean session marker.
- Weather location: hover the small weather control at the lower-right of the live window to search and select a city or postal code. The selected location is stored locally in the Windows user registry.
- Window settings: choose opacity from 100% (opaque) to 10% in 10-point steps, cycle the live window between normal, always-on-top, and always-in-background placement, and choose whether the live window appears in the Windows taskbar. These settings are stored locally and can be changed while the live window is open; hiding the taskbar entry does not hide the desktop window.
- The live-status footer gives a compact, informational view of CPU, RAM, GPU, occupied VRAM, and an available GPU power reading. Pastel yellow and red indicate medium and high utilization. Unsupported values show
—and never affect the watcher. - Start with Windows: starts only the tray app when you log in. It does not automatically arm a night run.
For maintainers, windows/Test-HerdrNightWatchPowerGuard.ps1 is a non-destructive Windows smoke test for this protection. Run it from an elevated PowerShell; it verifies activation and release with powercfg /requests and never sleeps or shuts down the computer.
If a live-window start ever fails, the tray reports the failure and records a
diagnostic line in the local logs/ui-errors.log file. This file is runtime
data and is never part of the repository.
Weather data uses Open-Meteo's geocoding and forecast services. The location, temperature, and moon phase are never used by the safety-critical watcher.
The Herdr Night Watch source code is MIT-licensed. The weather feature is a
runtime service integration and has separate provider terms. Open-Meteo's free
API is limited to open-source and non-commercial use, is rate-limited, and
requires attribution. The Forecast API data used for temperature and the
moon_phase value are provided under CC BY 4.0.
The Geocoding API data used for the searchable location picker are provided
under CC BY-NC 4.0.
For commercial deployments, use an appropriate Open-Meteo commercial/customer
plan or replace the weather provider. See THIRD_PARTY_NOTICES.md
for the exact notices and links. The core Herdr watcher remains usable under
the MIT license without the weather feature.
The Python watcher lives at watcher/herdr-night-watch.py; its safety contract remains authoritative.
- Set up WSL with a working Herdr CLI and an Ubuntu distribution.
- Choose a WSL path for
watcher/herdr-night-watch.py. - Start
dist/Herdr-Nachtwaechter.exeand open Open setup from its tray menu. - Enter the WSL distribution and watcher path, then start a night mode from the tray app.
The EXE is a convenience artifact for Windows. For other architectures or after source changes, rebuild it from src/.
The tooltip and live status window show the current Herdr count for information only. If Herdr cannot be read, the app never invents a number and the shutdown decision remains fail-closed.
An armed night run never survives a Windows or WSL restart. The watcher compares a composite WSL and Windows boot marker, uses a 30-second cache for ordinary status display, and forces a fresh comparison at safety-critical transitions. A changed marker clears any stale warning, records the reset, and returns to the safe inactive state. A new night run must always be started deliberately.
In a real night run, five seconds of confirmed inactivity starts the configured watcher-internal warning period, which defaults to 300 seconds and can be saved between 10 and 3,600 seconds. The tray and live window show that warning and can cancel it without touching unrelated Windows power actions.
The complete technical documentation for future changes starts at docs/INDEX.md. It covers states, the Windows/WSL boundary, builds and delivery, and safe troubleshooting. Runtime data, logs, and personal state files do not belong in Git.
The tray icon is based on Google’s official Material bedtime icon and is licensed under Apache-2.0. Its color changes by state: gray, green, blue, yellow, or red.