theme-agent developer docs

theme-agent is a cross-platform, unprivileged light/dark appearance controller for one user session. A single daemon resolves an effective light or dark theme from manual, system, sun-schedule, and fallback inputs. The CLI, native tray, Neovim plugin, and other clients use local IPC to read and change that shared state.

Local-first by design

• No internet access, telemetry, automatic geolocation, or public network listener.
• No root or administrator access. Services and IPC are scoped to the current user.
• One per-user daemon owns mutable theme state; clients do not duplicate OS detection.
• Optional hooks execute as argv without a shell and only when configured.

Repository layout

Path	Responsibility
crates/theme-core/	Synchronous, platform-neutral domain types, resolver, configuration, sun math, events, IPC protocol, and errors.
crates/theme-agent/	The binary: CLI, daemon, IPC transport, platform backends, services, and tray.
lua/, plugin/	The companion Neovim plugin, loadable from the repository root.
xtask/	Workspace version checks and SemVer updates.
website/	Marketing site and these developer docs.

Start here

• Getting started: install the binary, register the user service, and verify the daemon.
• Modes and scheduling: understand resolution precedence and offline sun calculations.
• Configuration: configure modes, location, sun elevation, and hooks.
• Neovim integration: keep editor colors synchronized with daemon state.

Reference

• CLI reference: commands, output contracts, services, and tray behavior.
• Local IPC: build a local client against the NDJSON protocol.
• Platform support: compare detection, appearance application, and user services.

Contributing

• Architecture: follow daemon ownership, event flow, and crate boundaries.
• Development: build, test, version, and verify workspace changes.

For implementation details, browse the repository source.