matugen: Material You and base16 palette generation with a Chumsky-based template engine

From a single image or hex color to a palette applied across every config file

matugen (pronounced: mat-uh-gen) solves a coordination problem that appears whenever a desktop theme changes: propagating that change to a dozen separate config files in different formats. The tool takes one input, either an image file or a hex color value, derives a complete Material You or base16 palette from it, and then rewrites every config file that has a corresponding template. No manual color copying is involved after setup.

Material You is the tonal palette system from Material Design 3. It derives tone variants and semantic roles for surfaces, text and accents from a source color. Base16 maps colors to a 16-slot scheme used by many terminal emulators and text editors. matugen can generate either format from the same input, so a user who wants Material You for a status bar and base16 for a terminal editor can do both in one run.

A community templates repository at InioX/matugen-themes holds pre-made templates for common programs, though the README does not enumerate which programs are covered there.

Chumsky-based parser in a separate workspace crate treats each color as a structured object

The templating engine is not built on a general-purpose library. Its parser lives in a separate Rust crate, matugen-parser, which is a member of the workspace defined in Cargo.toml. Chumsky is the parser combinator library used to build it.

Colors enter the engine as structured objects rather than raw strings, which is the design decision that enables format switching. Import a color once and the template can reference it as hex, rgb, rgba, hsl, or any other supported format in the same file without separate declarations. The README lists hex, rgb, rgba and hsl as output format examples.

Beyond color access, the engine supports piping, nested expressions, conditionals, loops, filters, includes, arithmetic operations and escaping output. The standalone mode is also documented: you can feed the engine a custom JSON file in place of a generated palette, detaching it from the color generation entirely.

Installing via Cargo, Arch Linux or NixOS flake and generating a first palette

Installing from crates.io requires one command:

cargo install matugen

Arch Linux users have two routes: the AUR package and the Arch extra repository.

yay -S matugen-bin

sudo pacman -S matugen

NixOS support is via a flake, but the README's NixOS section is truncated in the documentation available at GitHub; the complete setup is covered in the wiki at iniox.github.io/#matugen.

After installation, generate a palette from a wallpaper:

matugen image path/to/wallpaper.jpg

Or from a hex color directly:

matugen color hex "#ff0000"

To see every available option, run:

matugen --help

The tool runs on Windows, Linux, macOS and NetBSD. Platform-specific dependencies are included automatically by Cargo: winapi on Windows and enquote on macOS, both listed in Cargo.toml under target-specific sections.

Keyword filters chain hue, saturation, lightness and opacity adjustments inline in templates

Every color keyword in a template can pass through one or more filters before output. Built-in general filters include replace, to_upper and to_lower. Dedicated color filters cover hue, saturation, lightness, opacity and set_lightness. Filters chain in sequence, so adjusting saturation and then clamping lightness can happen in a single template expression.

Chaining is what separates this from simple placeholder substitution. A template for a dark status bar can take a Material You background color, reduce its lightness with set_lightness, then output a hex value, all within one token. No post-processing script is needed.

The filter documentation lives in the wiki at iniox.github.io/#matugen/filters. A filter-docs feature flag exists in Cargo.toml; it is off by default and is listed separately from the default feature set.

Custom JSON imports put arbitrary values into the template namespace alongside palette colors

Any JSON file can be imported through the CLI or through the config file, and its contents become keywords inside templates. Values declared as colors receive the same multi-format access as built-in palette colors: hex, rgb, rgba, hsl and other formats are all accessible from a single import.

This means templates are not limited to Material You or base16 slots. Project-specific tokens, environment flags or an entirely different color scheme can enter the namespace this way. The example/ directory contains three custom JSON examples, at example/custom.json, example/custom2.json and example/custom3.json, showing the expected file structure.

The config file format is TOML, with example/config.toml as a reference. Error handling examples live at example/config-error-testing.toml and example/error-testing.txt, which is an unusual inclusion for a project's example directory: it signals that the error paths have been considered enough to document.

A TypeScript compare script at the root uses Google's own color library alongside the Rust binary

The top-level repository layout includes compare-script.ts alongside Cargo.lock, Cargo.toml and flake.nix. The package.json shows its runtime dependencies: @material/material-color-utilities at ^0.3.0 and sharp at ^0.34.3, with TypeScript devDependencies. Google's own reference implementation for Material You color generation runs on the JavaScript side via @material/material-color-utilities, and the Rust binary uses material-colors 0.4.0. The README does not describe what this script produces or when to run it, but its presence in the repository root means the color output can be compared against Google's own implementation.

The Cargo.toml specifies license = "GPL-2.0-or-later", while the repository metadata records it as GPL-2.0, and the two variants differ in whether use under later versions is permitted. Any project that links to or includes this code needs to verify which statement controls before distributing.

pywal and wpgtk offer more backends; Mitsugen handles the gnome-shell case

pywal generates color schemes from images using multiple color generation backends and ships with default theme files for common applications. It predates Material Design 3 and does not generate Material You palettes, so the two tools occupy different positions: pywal for breadth of backends, matugen for Material You accuracy.

wpgtk builds on pywal and adds a graphical interface alongside more features. Neither pywal nor wpgtk matches matugen's approach of treating colors as typed objects with format conversion built into the template engine.

Mitsugen is a third option the README names, described as a gnome-shell tool based on the old Python version of matugen, which lives in a separate branch of the matugen repository. Mitsugen is downstream of that Python branch, not of the current Rust codebase. For GNOME Shell specifically, Mitsugen is the more direct choice; for everything else matugen and pywal are the practical alternatives.

Editorial conclusion

matugen suits Linux and macOS users who manage dotfiles and want to propagate a wallpaper's Material You palette to every config file with a single command. Skip it if you need a graphical wallpaper picker, color backends beyond Material You and base16, or a gentler learning curve than a custom template syntax demands. pywal and wpgtk cover those cases better. Before redistributing or embedding matugen in another project, read the LICENSE file at the repository root, because the Cargo.toml and repository metadata do not agree on which GPL variant applies. The wiki at iniox.github.io/#matugen documents the complete template syntax and filter reference.

Frequently asked questions

Official sources

1. InioX/matugen on GitHub
2. License: GPL-2.0
3. Project website
4. README
5. Releases