Re:fox

🎨 Dynamic theming of Firefox-based browser using your Native color scheme generator, [A fork of Pywalfox]

What's new?

Pywalfox does a great job theming the Firefox UI ~ toolbar, tabs, the works. But the moment you load a website, you're back to whatever colors that site decided on. This fork fixes that by pushing your Color palette into websites too, via CSS custom properties injected at page load. And since it hot reloads, running pywalfox update updates every open tab on the spot ~ no explicit tab refresh needed.

showcase_refox.mp4

Gecko Browser Stylesheets

• userChrome.css
• userContent.css

List of all websites

• Arch Linux
• ChatGPT
• Chess.com
• Claude
• Discord
• GitHub
• Monkeytype
• Reddit
• Telegram
• Twitter / X
• WhatsApp
• YouTube

⏺ Installation

1. Get the latest add-on from Releases Page and pin it to toolbar for a surprise.

   • It does autoupdate 😅

2. Install the native messaging host and browser templates using one of the two methods below:

   Method 1: Automated Installation / Updater (Arch Linux / Arch-based)

   Run our one-line curl installer (which also acts as an updater) in your terminal to automatically clone and set up Re:fox across your browsers:

   curl -fsSL https://raw.githubusercontent.com/ADIOR-enigma/refox/main/install.sh | bash

   • Canonical Location & Automatic Updates: The installer automatically clones (and on subsequent runs automatically pulls the latest updates to) the repository at ~/.config/refox.
   • Multi-Profile Setup: You will be prompted to paste your Profile Directory paths directly from about:support (supports multiple profiles across Firefox, LibreWolf, Floorp, Mercury) and whether you want to set up Matugen UI theming for Zen Browser.
   • Saved Configuration: Your profile paths are saved to ~/.config/refox/install.conf. Re-running ~/.config/refox/install.sh (or the one-line curl command) automatically updates all saved profiles without prompting, unless you choose to add more profiles.
   • Note: After installation completes, remember to open about:config in your browser(s) and verify toolkit.legacyUserProfileCustomizations.stylesheets is set to true.

   Method 2: Manual Installation (All platforms / other distributions)

   1. Install the native messaging application (PyPI) using your preferred method, with e.g. pip or pipx (or use the AUR package):

      pipx install pywalfox

      Don't have pipx? Install it first, then re-run the command above:

      • Arch Linux: pacman -S python-pipx
      • Ubuntu: apt install pipx
      • macOS: brew install pipx
      • Windows: winget install Python.Python.3.14, then pip install pywalfox instead

   2. Run pywalfox install in your terminal.
      • Firefox forks (e.g. LibreWolf) require extra arguments. Flatpaks require extra steps.
   3. Match manifest with Re:fox: Because Re:fox is forked from Pywalfox, edit the generated manifest file (~/.mozilla/native-messaging-hosts/pywalfox.json or ~/.config/mozilla/native-messaging-hosts/pywalfox.json on Linux/macOS or system/fork/Windows equivalent) and add "re-fox@adior.org" to allowed_extensions:

      {
        "name": "pywalfox",
        "description": "Automatically theme your browser using the colors generated by Pywal",
        "path": "/path/to/bin/main.sh",
        "type": "stdio",
        "allowed_extensions": ["pywalfox@frewacom.org", "re-fox@adior.org"]
      }

3. To add the templates (userChrome.css, userContent.css, and websites/) to your browser:

   • Navigate to about:support in your browser, look for Profile Directory, and click Open Directory.
   • Create a chrome folder inside your profile directory if it does not already exist.
   • Copy the contents of the template/ folder (userChrome.css, userContent.css, and the websites/ folder) into <profile-directory>/chrome.

4. Navigate to about:config and set toolkit.legacyUserProfileCustomizations.stylesheets to true.

5. Generate a theme with Matugen or equivalent. You may refer to there guide where the output must be $HOME/.cache/wal/colors.json.

6. Changing your wallpaper should theme the firefox or you can click the Refox icon in the Firefox UI and then "Fetch Native colors". Note that website theming is opt-in and not turned on by default, so you must open the extension settings to turn it on yourself.

This should apply a theme with your Native colors!

Note

If you have problems: please review the Troubleshooting section below before opening a Github issue/PR.

🧘 Zen Browser Matugen Support

Dynamic UI theming for Zen Browser using Matugen ($HOME/.cache/wal/colors.json) is fully supported and can be automatically installed via install.sh (Method 1). E.g.:

curl -fsSL https://raw.githubusercontent.com/ADIOR-enigma/refox/main/install.sh | bash

During automated setup, install.sh will prompt for your Zen profile and application directories, install config.js/defaults/ into your Zen binary folder, copy the userChromeJS watch scripts (refox_accent_watch.uc.js) to your Zen profile's chrome/ directory, and automatically configure the target cache path ($HOME/.cache/wal/colors.json) for your user.

Manual Zen Setup (if not using install.sh)

If you prefer manual installation:

1. Copy the contents of zen/program/ (config.js and defaults/) directly into your Zen browser application directory (where the zen-bin binary is installed).
2. Copy the contents of zen/chrome/ (JS/ and utils/) into your Zen profile's chrome/ directory (about:support -> Profile Directory -> chrome/).
3. The script refox_accent_watch.uc.js will monitor your Matugen colors.json and hot-reload your theme.

Note

If installing manually, be sure to update const PATH inside refox_accent_watch.uc.js to match your actual $HOME/.cache/wal/colors.json directory!

⏺ Usage

Update the theme through your terminal

Run pywalfox update in your terminal to trigger an update of the browser theme. This command can integrate Refox into e.g. system theming scripts, and is functionally equivalent to clicking "Fetch Native colors" in the add-on settings GUI (accessible from your toolbar).

Customization

The add-on settings GUI comes with extensive customization options divided into the following sections:

💧 Palette (click for details)

The palette in the "Palette" section is used to temporarily customize one or more colors from the Native color generated palette. You can use one of the generated colors, or choose any color from a colorwheel. Warning Changes to the palette will be reset when you click "Fetch Native colors" and when you run pywalfox update.

📝 Palette template (click for details)

If you want your palette customizations to be persistent (unlike the regular palette) you must save your current palette as a palette template: Click "Fetch Native colors" in the add-on settings GUI or run pywalfox update Customize the colors to your liking in the "Palette" section ❗ Colors from outside the Native color generated palette (i.e. from the colorwheel) cannot be used in a template. Click "Load from current" in the "Palette template" section below. ❗ The colors can also be set directly in the "Palette template" section using Native color indices. Click "Save palette" Your custom palette will now be applied whenever you update the browser theme.

🗂 ️Theme template (click for details)

The theme template assigns colors (from your palette template) to different browser elements. To create a palette template, go through the items in the "Theme template" section and assign a color to each item. The colors are identified by their names as seen in the "Palette template" section.

Theme modes

There are three different theme modes: "Dark" (❨), "Light" (𖤓) and "Auto" (👁)️. Selecting "Auto" will automatically switch between the other two modes based on a time interval found in the "General" section of the add-on settings GUI.

Note

The dark and light modes have separate theme and palette templates. You will always modifiy the template for the currently selected mode.

Site theming with the "Expose Refox CSS variables to websites?"

Websites and the context menus are not available through the Theme API. Refox includes templates which can be used to apply those theme to most part of the internet.

⏺ Uninstall

To uninstall Re:fox from your system across all configured browsers and clean up the native messaging host, run our one-line curl uninstaller:

curl -fsSL https://raw.githubusercontent.com/ADIOR-enigma/refox/main/uninstall.sh | bash

Or if you already have the repository installed locally at ~/.config/refox:

~/.config/refox/uninstall.sh

🔧 Troubleshooting

This section lists some common problems and how to (hopefully) fix them. This troubleshooting guide from Mozilla may be of use if you encounter an error that is not listed here. First of all:

• Check the log in the Debugging section at the bottom of the Refox settings page for any errors.
• Verify that ~/.cache/wal/colors exists and contains colors generated by Your Native color scheme generator.
• Verify that path in ~/<native-messaging-hosts-folder>/pywalfox.json is a valid path.

Firefox forks

Forks may require custom paths to the manifest and profile directory during installation:

pywalfox install --manifest-path ~/.mozilla/native-messaging-hosts \
                 --profile-path  ~/.config/librewolf/librewolf

The above example is for LibreWolf (non-Flatpak version). Paths vary across forks.

Note

If you run pywalfox install manually for a fork, remember to edit the created manifest (~/.mozilla/native-messaging-hosts/pywalfox.json or your fork's native-messaging-hosts directory) and ensure "re-fox@adior.org" is added to "allowed_extensions" so Re:fox can connect.

Flatpaks

Flatpak sandboxing prevents direct access to host binaries, so a wrapper script is needed. The steps below use the LibreWolf Flatpak as an example. You may need to adapt the instructions for your particular browser.

1. Create a wrapper script at ~/.var/app/io.gitlab.librewolf-community/pywalfox-wrapper.sh:

   #!/bin/sh
   flatpak-spawn --host ~/.local/bin/pywalfox "$@"

2. Make the wrapper script executable:

   chmod +x ~/.var/app/io.gitlab.librewolf-community/pywalfox-wrapper.sh

3. Install the native messaging host with additional arguments for your particular paths, e.g.

   pywalfox install \
   --manifest-path ~/.var/app/io.gitlab.librewolf-community/.librewolf/native-messaging-hosts \
   --profile-path  ~/.var/app/io.gitlab.librewolf-community/.librewolf/

4. Edit the manifest (~/.var/app/io.gitlab.librewolf-community/.librewolf/native-messaging-hosts/pywalfox.json) and point its path to the wrapper script. Use an absolute path as below (replacing <USER> with your username), and make sure "re-fox@adior.org" is in allowed_extensions:

   {
     "name": "pywalfox",
     "description": "Automatically theme your browser using the colors generated by Pywal",
     "path": "/home/<USER>/.var/app/io.gitlab.librewolf-community/pywalfox-wrapper.sh",
     "type": "stdio",
     "allowed_extensions": ["pywalfox@frewacom.org", "re-fox@adior.org"]
   }

5. Grant Talk permissions:

   flatpak override --user \
     --talk-name=org.freedesktop.Flatpak \
     --talk-name=org.freedesktop.portal.Flatpak \
     --system-talk-name=org.freedesktop.Flatpak \
     io.gitlab.librewolf-community

   Verify that the correct permissions have been granted, i.e.

   flatpak override --user --talk-name=org.freedesktop.Flatpak io.gitlab.librewolf-community

   should output

   [Session Bus Policy]
   org.freedesktop.Flatpak=talk
   org.freedesktop.portal.Flatpak=talk
   
   [System Bus Policy]
   org.freedesktop.Flatpak=talk

6. Restart the browser. Fetching Native/Pywal colors should now work.

Common errors in the browser console

It is a good idea to check the Firefox browser console (Tools > Web developer > Browser console) for errors. Common errors include:

ExtensionError: No such native application pywalfox / ExtensionError: No such native application refox

The manifest is not installed properly or is missing allowed extensions. Try installing/checking the manifest manually by following the instructions here. The manifest file (pywalfox.json) must be located in your browser's native-messaging-hosts directory (e.g. ~/.mozilla/native-messaging-hosts/pywalfox.json or /lib/mozilla/native-messaging-hosts/pywalfox.json). Ensure the path property points to <path-to-python-site-packages>/pywalfox/bin/main.sh (or win.bat if you are on Windows), and verify that allowed_extensions contains "re-fox@adior.org". If it still does not work, you can try to reinstall Firefox.

stderr output from native app pywalfox: /main.sh: line 3: pywalfox: command not found

Refox assumes that the pywalfox executable is in your PATH. If you can not run pywalfox from the command line (without specifying an absolute path), you must either add the path to the executable to your PATH variable, or move the executable to a path that already is in your PATH.

Important

The errors in the browser console are not limited to just Refox!

POST PRs TO THE >dev< BRANCH

🚧 Development setup

Do you want to hack on the Refox add-on? Start here:

git clone https://github.com/ADIOR-enigma/refox.git # or use your own fork
cd refox
yarn install # or npm if you do not have yarn installed
yarn run debug

To build the extension into a zip:

yarn run build

🙏 Credits & Acknowledgments

Refox builds upon the fantastic work of several projects and individuals in the open-source community:

• Frewacom and all contributors of Pywalfox – for creating and maintaining the original project that Refox is forked from.
• TECHNOFAB11 – for their idea on injecting CSS custom properties into websites (Pywalfox PR #161).
• Ubaidullah-Web-Dev (ubaid) – for MatugenFox and inspiration on Matugen-driven browser theming.