monocoat

One TOML, every Linux theming surface. monocoat (formerly archstylix) drives GTK 2/3/4, xsettings, the window manager, Qt/Kvantum, notifications, the cursor (optionally generated from the palette), fonts, colors, the dock, the launcher, the panel, the wallpaper (optionally palette-following via monocoat watch), Firefox chrome, a picom effects stack (CRT shaders, client and frame glass) and an xrdp overlay from one file: ~/.config/monocoat/monocoat.toml.

The TOML is canon. Every layer is re-derived from it on each monocoat apply, so settings that a GUI dialog changed behind your back show up as drift and get overwritten. Applying twice is a no-op: a layer whose live value already matches reports "unchanged" and writes nothing.

See TODO.md for the current prioritized backlog, audit findings, acceptance gates and a rough project-readiness assessment. The state-role and ownership reference documents Kitty include precedence, static doctor coverage, cross-consumer interaction roles and the retained opaque-frame/glass-client policy.

Why

A Linux desktop keeps its look in a dozen independent places: xfconf channels, gsettings keys, settings.ini files, Kvantum and qt5ct/qt6ct configs, rofi .rasi files, polybar templates, notification CSS. GUI dialogs each write a few of them. Drift is the normal state. monocoat writes all of them from one description and can tell you which ones have drifted since.

Install

From a clone, no install step (the CLI is stdlib-only):

git clone https://github.com/blakebratcher/monocoat.git ~/src/monocoat
ln -s ~/src/monocoat/bin/monocoat ~/.local/bin/monocoat

bin/monocoat adds the repo's src/ to sys.path and calls monocoat.cli:main, so there is no pip, venv or PEP 668 step.

As a package, from the same clone:

cd ~/src/monocoat
pipx install .

monocoat is not on PyPI yet, so pipx install monocoat does not work. Install from a clone until a release is published there.

Requires Python 3.11 or newer. Four optional tools are needed only by the features that use them: ImageMagick (magick) for monocoat generate, rsvg-convert (librsvg) for the palette-following cursor ([appearance].cursor_source), sassc for deep_recolor's SCSS-bound assets, and pywal (wal) for the panel layer's polybar template re-render. Everything else runs on the standard library alone.

Quickstart

monocoat init                # write a starter ~/.config/monocoat/monocoat.toml
# or
monocoat init --from-live    # seed it from the desktop you're running now (XFCE)

monocoat apply --dry-run     # preview every change; nothing is written
monocoat apply               # write it

init --from-live followed by apply is designed to be a no-op: the config describes what is already live.

For a fuller starting point, copy examples/monocoat.toml. It uses only stock assets (Adwaita, xfwm4's Default theme, fontconfig's Sans/Monospace) and documents the optional sections. Reserved settings are marked as having no effect rather than presented as working knobs:

mkdir -p ~/.config/monocoat
cp examples/monocoat.toml ~/.config/monocoat/monocoat.toml
monocoat apply --dry-run

If there is no config, every command that needs one exits 3 and tells you to run monocoat init (or monocoat migrate, if an archstylix config exists).

Commands

apply, status, diff, doctor, daynight, dock, generate, backup, import-mydockfinder, launcher-index and verify also take -q, -v and --json.

Exit codes

Presets

Keep several themes side by side in ~/.config/monocoat/presets/. The active one is whatever ~/.config/monocoat/monocoat.toml symlinks to.

~/.config/monocoat/
├── monocoat.toml -> presets/tahoe-dark.toml
└── presets/
    ├── tahoe-dark.toml
    ├── tahoe-light.toml
    └── reference-amber.toml

monocoat list                 # '*' marks the active preset
monocoat diff tahoe-light     # what switching would change
monocoat set tahoe-light      # retarget the symlink and apply
monocoat set sea --pin        # retarget + pin against `monocoat watch` switching
monocoat save tahoe-backup    # snapshot the active config as a new preset
monocoat edit                 # edit the active preset; re-applies on save

monocoat watch (opt-in [wallpaper].auto_switch) generates and switches among presets as the wallpaper changes, honouring a set --pin pin; it never deletes presets. See adaptive palettes.

Theme assets a preset needs (picom shaders, polybar configs, scripts) live in ~/.local/share/monocoat/themes/<preset>/ by default; set [paths].assets_dir to put them elsewhere.

Layers

monocoat apply runs these in order (see src/monocoat/registry.py):

On an X11 window manager using xsettingsd, local and remote settings have separate broker files: local uses $XDG_CONFIG_HOME/xsettingsd/xsettingsd.conf, and remote uses [remote].config_home/xsettingsd/xsettingsd.conf. Start the xrdp broker with the remote file (for example xsettingsd -c "$XDG_CONFIG_HOME/xsettingsd/xsettingsd.conf" when its XDG config home is the remote overlay). A remote xsettingsd symlink that resolves to the local broker is rejected with exit 4; replace that shared layout with an independent directory before applying. On XFCE, the existing local-file/remote-symlink layout is kept because xfconf owns the local settings broadcast.

A section that is absent from the config leaves its surface alone. To turn a layer off explicitly, set [layers].<name> = false.

Desktop support

The file-backed layers (GTK files, cursor, Qt, rofi and so on) don't depend on the desktop. Run monocoat doctor to see which layers your session can run and why the others can't.

Migrating from archstylix

monocoat is the renamed archstylix. The old theme command and bin/theme shim are gone. Use monocoat (the subcommands are the same).

The old config location ~/.config/theme/theme.toml (and its presets/) still works: monocoat reads it and prints a notice on every run. To move it:

monocoat migrate --dry-run    # show the plan: files moved, keys renamed or dropped
monocoat migrate              # move ~/.config/theme → ~/.config/monocoat, rewrite presets to schema v2
monocoat apply --dry-run      # a migrated XFCE preset should report no changes

The v1 layout ([gtk], [xfwm4], [plank], [rofi], [polybar], [xrdp], [display]) becomes v2 ([appearance], [window_manager], [dock], [launcher], [panel], [remote], [scaling]). See examples/theme.toml (legacy v1) next to examples/monocoat.toml (v2).

Design notes

• Idempotent. Every write is read-compare-write. A clean system reports everything unchanged, and apply --dry-run exits 0.
• Drift is visible. monocoat diff exits 1 when something moved, so it works in scripts and login hooks.
• One owner for daemon restarts. Layers only write configuration. daemons.reload_daemons() restarts polybar, the dock unit and picom, and runs [daemons].palette_hooks and the xfwm4/GTK theme round-trips, and only for writes their layers actually made. Restarting from inside layers once stacked two polybars and crashed Plank.
• Never signals xfsettingsd. It has no SIGHUP handler, so a HUP kills it, and xfconf writes reach it live anyway.
• Stdlib-only CLI. PyGObject and pycairo are imported only by the Settings window and the dock.

Project layout

monocoat/
├── bin/monocoat              # no-install shim (sys.path → src/, calls cli.main)
├── examples/
│   ├── monocoat.toml         # v2 example, stock assets only
│   └── theme.toml            # legacy v1 sample (and test fixture)
├── src/monocoat/
│   ├── cli.py                # argparse, apply_cfg (the apply choke point)
│   ├── config.py             # config location + load/validate
│   ├── schema.py             # v2 schema, defaults, v1 → v2 upgrade
│   ├── registry.py           # ordered layer registry + capability gates
│   ├── capabilities.py       # what a session can do
│   ├── session/              # desktop/display detection, backends
│   ├── layers/               # one module per theming surface
│   ├── diff.py               # read-only apply → status / diff rows
│   ├── doctor.py             # monocoat doctor
│   ├── daemons.py            # the single-owner reload pass
│   ├── commands/             # init, migrate, demo
│   └── gui/                  # the Settings window (GTK3)
└── tests/

Contributing

See CONTRIBUTING.md: the layer protocol, the reload rule, the write helpers, and the sandbox rule every test follows.

License

MIT. See LICENSE. Vendored data keeps its own license: the Hackneyed cursor SVGs (MIT, src/monocoat/data/hackneyed) and the Han reading table derived from the Unicode Unihan database (Unicode License v3, src/monocoat/data/unihan).

Glass, frames, and pixel acceptance

See docs/schema.md for every canonical key/default and the ownership boundaries. [effects].glass (0–1) resolves to one alpha byte and drives every glass surface: kitty's background_opacity, rofi's background-glass, polybar's bg-glass, alpha(<bg>, …) in the GTK CSS, the Kvantum window/menu interiors, picom's global frame-opacity plus blur-background-frame (xfwm4 titlebars and borders join the glass), and the managed block in the bundle's firefox/userChrome.css (restart Firefox; the #browser rule extends the glass to the vertical-tabs sidebar). 0 leaves it unmanaged. Compiled GTK CSS and its SCSS sources stay in step. Toolbar bg_alt remains a distinct palette role from the bg glass body. GTK3 glass menus paint their background once on the outer popup; child menus and decorations stay transparent. With local themed XFCE notifications, the notifications layer manages /initial-opacity at 1 so the daemon does not multiply the CSS alpha by its default 0.9.

The system-Python fixture scripts/glass-popup.py gtk (or qt) opens a short-lived actual toolkit menu and reports its X11 ID and size. GTK fixtures require PyGObject/GTK3; Qt fixtures require PyQt5. The fixture selects an RGBA visual for GTK, writes no theme config, and takes focus while open; the parent measurement must save/restore focus. --css PATH lets a GTK fixture load a candidate stylesheet without installing it. See the menu/notification acceptance record for the measured default and candidate results.

shader_titlebar = "auto" (the default) reads the configured XFWM theme's frame images. A nonnegative integer overrides the top height; 0 switches frame shading off. Side/bottom borders use their actual image dimensions. Maximized windows with no side/bottom frame get a separate top-only rule.

monocoat doctor checks the reference shader's screen-space scanline raster and premultiplied-alpha depth correction. Those source checks do not prove rendered pixels. For an opt-in live X11 measurement, select an empty 32×8 region in each visible application (a frame surface takes the FRAME window id with an offset inside the titlebar), then run:

xdotool search --onlyvisible --class kitty
xdotool search --onlyvisible --class Rofi
monocoat verify --surface kitty:0xWINDOW_ID:200:100 \
                --surface rofi:0xWINDOW_ID:200:100 \
                --surface frame:0xFRAME_ID:200:8 --json

Replace the IDs and offsets with the actual windows/empty regions. Offsets are relative to each client (for frame, inside the titlebar). The command puts a 128×64 black/white patch below each window, reads lit/dim screen rows, solves alpha and premultiplied RGB, and fails on any RGB-byte or screen-phase difference. It rejects text, gradients, opaque or obscured samples and unsupported sessions. The temporary patch is destroyed even on failure, focus is restored, and no theme files or application configs are written. Exit 0 proves equality only for the selected regions; JSON names catalogued surfaces that were not measured (kitty, rofi, dolphin, gtk-menu, qt-menu, notification, task-list, frame). Straight RGB is an estimate because premultiplication rounds; exact equality uses the measured black/white pixels.

After glass/palette changes, apply lists running known applications that may retain old settings until restarted. This notice is not a runtime acceptance claim. ./scripts/check runs pinned lint and the sandboxed test suite before pushing; the suite includes the schema-document drift gate.

The resident dock also accepts monocoat dock --toggle, --show, --hide and --launchpad (open or close its Launchpad) for hotkeys. Its preset controls four edges, per-output scale, visibility policies, icon effects, built-in/file pins and opt-in lock-gated window previews. See the dock guide.