Getting started

Prerequisite

theme-agent requires Rust 1.88 or newer. The workspace manifest enforces this MSRV, and a checkout selects stable through rust-toolchain.toml. Git installs run from your current directory, so invoke Cargo with +stable explicitly.

rustup update stable
cargo +stable --version
rustc +stable --version

Install from Git

The recommended install is locked to the repository’s dependency graph:

cargo +stable install --locked --git https://github.com/Ajaymamtora/theme-agent theme-agent

Then register the current binary as a user service:

theme-agent service install
theme-agent service status

service install is safe on a first install and on upgrades. It preserves configuration, updates the registered binary path, starts the daemon immediately, and enables it at login without admin privileges. Cargo has no post-install hook, so update the binary and service separately:

rustup update stable
cargo +stable install --locked --force --git https://github.com/Ajaymamtora/theme-agent theme-agent
theme-agent service update

service update is an alias of service install that makes the upgrade intent explicit. To pin a release, add --tag vX.Y.Z once the corresponding tag exists.

Local and headless installs

From a checkout:

git clone https://github.com/Ajaymamtora/theme-agent
cd theme-agent
cargo install --locked --path crates/theme-agent

To build without installing:

target/release/theme-agent

cargo build --release

Cargo installs binaries into ~/.cargo/bin; ensure it is on PATH.

The native tray feature is enabled by default. Linux tray builds require GTK/appindicator development libraries such as libgtk-3-dev, libxdo-dev, and libayatana-appindicator3-dev on Debian or Ubuntu. For servers, CI, or systems without those libraries, install a headless daemon and CLI:

cargo +stable install --locked --no-default-features --git https://github.com/Ajaymamtora/theme-agent theme-agent

Verify the daemon

Run it directly in the foreground:

theme-agent daemon --log-level info

Or use the registered service:

theme-agent service install
theme-agent service status

From another shell, inspect state, make a transient mode change, and watch events:

theme-agent status                 # human-readable state
theme-agent status --json          # machine-readable state
theme-agent set dark               # manual dark override
theme-agent set system             # follow the OS
theme-agent set sun                # follow sunrise/sunset; requires a location
theme-agent subscribe              # stream changes; Ctrl-C to stop

set changes the running daemon only. To persist a default, continue with Modes and scheduling and Configuration.

Fix a stale or mixed toolchain

Errors such as found crate ... compiled by an incompatible version of rustc or E0514 usually indicate stale artifacts, a mixed toolchain, or rustc wrappers rather than an MSRV problem. Retry with stable and remove build overrides from the install process:

rustup update stable
env -u RUSTC -u RUSTDOC -u RUSTC_WRAPPER -u RUSTC_WORKSPACE_WRAPPER \
  -u CARGO_TARGET_DIR -u CARGO_BUILD_TARGET_DIR -u CARGO_BUILD_BUILD_DIR \
  -u CARGO_BUILD_RUSTC -u CARGO_BUILD_RUSTDOC \
  -u CARGO_BUILD_RUSTC_WRAPPER -u CARGO_BUILD_RUSTC_WORKSPACE_WRAPPER \
  cargo +stable install --locked --force --git https://github.com/Ajaymamtora/theme-agent theme-agent
theme-agent service update

Confirm the selected tools with cargo +stable --version and rustc +stable --version.