Skip to content
theme-agent

Modes and scheduling

The daemon always resolves one effective value: light or dark. Its source field records which input won: manual, system, sun, or fallback.

Five control modes

Section titled “Five control modes”
Mode Resolution
light Always light.
dark Always dark.
system Current OS preference, then the configured fallback.
sun Offline sun calculation, then the configured fallback. Requires a location.
auto OS preference, then sun calculation, then the configured fallback.

The fixed precedence is manual > system > sun > fallback. light and dark are manual overrides. system, sun, and auto walk only the inputs shown above; resolution never produces an unavailable or intermediate value.

Status exposes the active mode, resolved effective value, last known system and sun inputs, fallback, manual override, location, next_transition, and daemon start time.

Transient and persistent changes

Section titled “Transient and persistent changes”
Terminal window
theme-agent set dark
theme-agent set auto

theme-agent set <mode> changes the running daemon but does not persist the default. Use the configuration command when the mode must survive a restart:

Terminal window
theme-agent config set mode auto

That command edits config.toml; the file watcher live-reloads the value into a reachable daemon. See Configuration for the complete schema.

Offline sun scheduling

Section titled “Offline sun scheduling”

Sun mode performs no network or geolocation lookup. theme-core implements NOAA-style solar equations and uses timezone-aware timestamps, including daylight-saving transitions. The calculation was informed by Alexander Yakushev’s lustrous.lua, as used by circadian.nvim and released under CC0 1.0. You provide coordinates explicitly:

Terminal window
theme-agent config set location 51.5072 -0.1276
theme-agent config set mode sun

Supported bounds:

  • latitude: [-90, 90];
  • longitude: [-180, 180];
  • solar switch elevation: [-18°, 18°];
  • default elevation: -0.833°, the conventional sunrise/sunset value;
  • -6° approximates civil twilight.

The daemon schedules the calculated next transition, caps sleeps at six hours, and wakes with a 60-second guard so suspend/resume cannot leave sun state stale indefinitely.

Polar day and polar night are supported. If a date has no intra-day transition, the daemon forces a recomputation on the next local day. Timezone and DST boundaries are handled using the coordinates’ local scheduling context.

Missing inputs

Section titled “Missing inputs”

Explicit sun mode is rejected if no location is configured. auto remains valid: it uses system appearance when available, then sun data when a location exists, and finally the configured fallback when neither source is available.