Breeze Shell replaces the Windows 11 context menu with a scriptable one

What Breeze Shell replaces on Windows 10 and 11

The Windows context menu is a fixed surface. You get the entries the shell and installed applications register, in an order you did not choose, with a look you cannot change. Breeze Shell replaces that menu with its own, aimed at Windows 10 and Windows 11, and the README describes it as an alternative context menu. The target reader is someone who right-clicks files and folders all day and wants that interaction to be theirs: item height, background radius, animation speed, and the set of commands that appear.

The project is not a launcher and not a file manager. It sits where the shell menu sits, and the README lists Microsoft Explorer as fully compatible and OneCommander as mostly working. That table is short, and it is the honest limit of what the project claims about where it plugs in. If your daily driver is a file manager that is not on that table, you are guessing.

How the menu, the renderer and the JavaScript layer fit together

Breeze Shell is C++ and builds its interface on breeze_ui, a UI library the project also maintains, which supports both NanoVG and ThorVG as render contexts. That choice explains the size claim in the README: a user interface in roughly 2MiB. Animation is a first-class concern rather than a later addition, which is why the README says all animations are configurable, scalable and can be disabled.

The extension path is an embedded JavaScript engine. The README credits quickjs-ng and quickjspp among the third-party libraries, and exposes a shell object to scripts. A script registers a listener on the menu controller and adds items to the menu when it fires. The bindings live in src/shell/script/binding_types.d.ts, which is the file to read before writing anything nontrivial, because the README shows one example and points there for the rest.

Configuration is separate from scripting. CONFIG.md and CONFIG_zh.md sit at the repository root and cover settings from item height to the background radius method. The README notes that the config menu is reachable by opening your Data Folder and right-clicking anywhere inside it, which is an unusual entry point and worth remembering, since there is no settings window described anywhere else.

Installing Breeze Shell and writing a first script

The README does not describe an installer. It says to download and extract the zip and run breeze.exe. There is no package manager step, no winget command, and no MSI mentioned, so treat the zip as the distribution channel and expect to keep the extracted folder where you want it to live.

After the first run, the README points to the Data Folder as the place where configuration lives. Open it and right-click inside it to reach the config menu. That is the whole documented setup path.

To extend the menu, add a listener through the shell object. This is the example the README gives, which adds a button that shuffles the positions of existing menu items:

shell.menu_controller.add_menu_listener((e) => {
  e.menu.add({
    type: "button",
    name: "Shuffle Buttons",
    action: () => {
      for (const item of menus) {
        item.set_position(Math.floor(menus.length * Math.random()));
      }
    },
  }, 0);
});

The shape to notice is the second argument to add, the 0, which places the item. The action callback receives no arguments in this example; the loop reads a menus variable from the surrounding scope, so the example assumes that binding is already in scope where your script runs. Check binding_types.d.ts for the real signature before copying this.

If you would rather not write your own, the README says pull requests go to the breeze-shell/plugins repository to add a script to the plugin market. That is a contribution route, not a documented install command, so do not expect a one-line plugin install from the README alone.

Building from source is a separate path. The README states the project uses xmake, that xmake must be installed first, and that running xmake in the project directory and following the instructions is the build step. Both clang-cl and MSVC 2019 or newer can build it. After one successful build, the README suggests opening the project directory in VSCode with the clangd plugin for intellisense.

Where Breeze Shell is the wrong tool

The README carries a warning at the top: the project is still in active development, and it asks you to file a bug report if you meet any. That is a direct statement about stability, and it should shape where you deploy this. On a personal machine, a misbehaving context menu is an annoyance. On a shared or managed workstation, the shell menu is on the path to every file operation, and an unfinished replacement there is a liability.

The compatibility table is the second constraint. Microsoft Explorer is marked fully compatible; OneCommander is marked as mostly working. Nothing else is listed. Shell extensions written by other applications expect the standard menu host, and the README does not claim any compatibility layer for them, so a workflow that depends on a specific third-party shell extension is unproven here.

There is also a documentation gap around failure. The README explains how to configure and extend the menu but says nothing about what happens when a script throws, how to disable Breeze Shell if it misbehaves, or how to roll back to the stock menu. Those are the questions to answer before you put it on a machine you cannot easily reimage.

Breeze Shell against Nilesoft Shell and Moudey Shell

The obvious comparison is Nilesoft Shell, which is what most people find when they search for a replacement shell menu on Windows 11, and which is configured through its own shell.nss file rather than through a scripting runtime. Nilesoft Shell is a configuration language; Breeze Shell is a JavaScript API. If you want to declare menu entries and conditions in a text file, Nilesoft Shell is the more direct fit. If you want to compute menu contents at open time, loop over items, and call methods like set_position, Breeze Shell gives you a general-purpose language to do it in.

The README credits moudey/Shell as inspiration and then states in capitals that all code in this rewrite is original and unrelated to it. That matters if you are choosing between them on the assumption that Breeze Shell is a fork. It is not, according to the project, so bug reports and fixes do not flow between the two.

The size claim is another axis. The README attributes the roughly 2MiB interface to breeze_ui and its NanoVG and ThorVG render contexts. Whether that matters to you depends on whether you care about a resident shell component's footprint, which is a reasonable thing to care about for something that loads on every right-click.

Licence, maintenance and what an upgrade costs you

Breeze Shell is AGPL-3.0. For an end user running breeze.exe on a desktop, that is a distribution licence question rather than a usage one, but it becomes concrete the moment you redistribute the binary inside a company image or link the code into your own product. The repository ships a LICENSE file at the root, and that is the text to read before you do either. This is not legal advice; if you are bundling it, ask someone who can give you some.

The release cadence visible in the repository is modest: 0.1.32 on 2025-12-13, 0.1.33 on 2026-03-06, 0.1.34 on 2026-04-12. The last push to the repository was on 2026-09-20, so work is happening between releases even when no tag lands. Version numbers are still in 0.1.x, which is consistent with the development warning in the README.

Upgrade cost is mostly the configuration surface. CONFIG.md is a separate document from the code, and the scripting API is defined in binding_types.d.ts, so a version bump can change either. The README does not document a migration process between versions, and it does not describe how configuration is versioned or whether old config files keep working. Back up your Data Folder before replacing the extracted binaries, because that folder is where the README says your configuration lives.

Editorial conclusion

Adopt Breeze Shell if you want a context menu you can script and style rather than a fixed one, and you accept that the README calls the project still in active development. Skip it if you need a stable tool for production machines, or if your workflow depends on shell surfaces the compatibility table does not list. Before installing, check the compatibility table against your file manager and confirm the script bindings in src/shell/script/binding_types.d.ts cover what you plan to write. The last push was on 2026-09-20.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. Project website
3. README
4. Releases
5. std-microblock/breeze-shell on GitHub