Whim is a pluggable and modern window manager for Windows 10 and 11, built using WinUI 3 and .NET. It is currently in active development.

Alpha builds are available on the releases page.

When you run Whim for the first time, it will create a .whim directory in your user profile - for example, C:\Users\Isaac\.whim. This can be configured with the CLI option --dir.

This directory will contain a whim.config.csx file which you can edit to customize Whim. This file is a C# script file, and is reloaded every time Whim starts. To have the best development experience, you should have dotnet tooling installed (Visual Studio Code will prompt you when you open .whim).

The config contains a pre-filled example which you can use as a starting point. You can also find the config here.

A "workspace" in Whim is a collection of windows. They are displayed on a single monitor. The layouts of workspaces are determined by their layout engines. Each workspace has a single active layout engine, and can cycle through different layout engines. For more, see Inspiration.

The WorkspaceManager object has a customizable CreateLayoutEngines property which provides the default layout engines for workspaces. For example, the following config sets up three workspaces, and two layout engines:

// Set up workspaces.
context.WorkspaceManager.Add("Browser");
context.WorkspaceManager.Add("IDE");
context.WorkspaceManager.Add("Alt");

// Set up layout engines.
context.WorkspaceManager.CreateLayoutEngines = () => new CreateLeafLayoutEngine[]
{
    (id) => new TreeLayoutEngine(context, treeLayoutPlugin, id),
    (id) => new ColumnLayoutEngine(id)
};

It's also possible to customize the layout engines for a specific workspace:

context.WorkspaceManager.Add(
    "Alt",
    new CreateLeafLayoutEngine[]
    {
        (id) => new ColumnLayoutEngine(id)
    }
);

When Whim exits, it will save the current workspaces and the current positions of each window within them. When Whim is started again, it will attempt to merge the saved workspaces with the workspaces defined in the config.

Whim is build around plugins. Plugins are referenced using #r and using statements at the top of the config file. Each plugin generally has a Config class, and a Plugin class. For example:

BarConfig barConfig = new(leftComponents, centerComponents, rightComponents);
BarPlugin barPlugin = new(context, barConfig);
context.PluginManager.AddPlugin(barPlugin);

Each plugin needs to be added to the context object.

Whim stores commands (ICommand), which are objects with a unique identifier, title, and executable action. Commands expose easy access to functionality from Whim's core, and loaded plugins.

Command identifiers namespaced to the plugin which defines them. For example, the whim.core namespace is reserved for core commands, and whim.gaps is used by the GapsPlugin to define commands. Identifiers are based on the Name property of the plugin - for example, GapsPlugin.Name.

Each plugin can provide commands through the PluginCommands property of the IPlugin interface.

Custom commands are automatically added to the whim.custom namespace. For example, the following command minimizes Discord:

// Add to the top.
using System.Linq;

void DoConfig(IConfig context)
{
    // ...

    // Create the command.
    context.CommandManager.Add(
        // Automatically namespaced to `whim.custom`.
        identifier: "minimize_discord",
        title: "Minimize Discord",
        callback: () =>
        {
            // Get the first window with the process name "Discord.exe".
            IWindow window = context.WindowManager.FirstOrDefault(w => w.ProcessFileName == "Discord.exe");
            if (window != null)
            {
                // Minimize the window.
                window.ShowMinimized();
                context.WorkspaceManager.ActiveWorkspace.FocusFirstWindow();
            }
        }
    );

    // Create an associated keybind.
    context.KeybindManager.SetKeybind("whim.custom.minimize_discord", new Keybind(IKeybind.WinAlt, VIRTUAL_KEY.VK_D));

    // ...
}

Commands can be bound to keybinds (IKeybind).

Each command is bound to a single keybind.

Each keybind can trigger multiple commands.

Keybinds can be overridden and removed in the config. For example:

// Override the default keybind for showing/hiding the command palette.
context.KeybindManager.SetKeybind("whim.command_palette.toggle", new Keybind(IKeybind.WinAlt, VIRTUAL_KEY.VK_P));

// Remove the default keybind for closing the current workspace.
context.KeybindManager.Remove("whim.core.close_current_workspace");

// Remove all keybinds - start from scratch.
context.KeybindManager.Clear();

Keybindings can also be seen in the command palette, when it is activated (Win + Shift + K by default).

These are the commands and associated keybindings provided by Whim's core. See CoreCommands.cs.

See CommandPaletteCommands.cs.

See FloatingLayoutCommands.cs.

See FocusIndicatorCommands.cs.

See GapsCommands.cs.

See TreeLayoutCommands.cs.

IRouterManager is used by Whim to route windows to specific workspaces. For example, to route Discord to a workspace "Chat", you can do the following:

context.RouterManager.Add((window) =>
{
    if (window.ProcessFileName == "Discord.exe")
    {
        return context.WorkspaceManager.TryGet("Chat");
    }

    // Continue routing.
    return null;
});

IFilterManager tells Whim to ignore windows based on Filter delegates. A common use case is for plugins to filter out windows they manage themselves and want Whim to not lay out. For example, the bars and command palette are filtered out.

// Called by the bar plugin.
context.FilterManager.AddTitleMatchFilter("Whim Bar");

The IWindowManager is used by Whim to manage IWindows. It listens to window events from Windows and notifies listeners (Whim core, plugins, etc.).

For example, the WindowFocused event is used by the Whim.FocusIndicator and Whim.Bar plugins to update their indications of the currently focused window.

The IWindowManager also exposes an IFilterManager called LocationRestoringFilterManager. Some applications like to restore their window positions when they start (e.g., Firefox, JetBrains Gateway). As a window manager, this is undesirable. LocationRestoringFilterManager listens to WindowMoved events for these windows and will force their parent IWorkspace to do a layout two seconds after their first WindowMoved event, attempting to restore the window to its correct position.

If this doesn't work, dragging a window's edge will force a layout, which should fix the window's position. This is an area which could use further improvement.

Whim wraps Serilog to provide logging functionality. It can be configured using the LoggerConfig class. For example:

// The logger will only log messages with a level of `Debug` or higher.
context.Logger.Config = new LoggerConfig() { BaseMinLogLevel = LogLevel.Debug };

// The logger will log messages with a level of `Debug` or higher to a file.
if (context.Logger.Config.FileSink is FileSinkConfig fileSinkConfig)
{
    fileSinkConfig.MinLogLevel = LogLevel.Debug;
}

// The logger will log messages with a level of `Error` or higher to the debug console.
// The debug sink is only available in debug builds, and can slow down Whim.
if (context.Logger.Config.DebugSink is SinkConfig debugSinkConfig)
{
    debugSinkConfig.MinLogLevel = LogLevel.Error;
}

Whim is heavily inspired by the workspacer project, to which I've contributed to in the past. However, there are a few key differences:

• Whim is built using WinUI 3 instead of Windows Forms. This makes it easier to have a more modern UI.
• Whim has a more powerful command palette, which supports fuzzy search.
• Whim stores windows internally in a more flexible way. This facilitates more complex window management. For more, see Layouts.
• Whim has a command system with common functionality, which makes it easier to interact with at a higher level.
• Creating subclasses of internal classes is not encouraged in Whim - instead, plugins should suffice to add new functionality.

Whim was not built to be a drop-in replacement for workspacer, but it does have a similar feel and many of the same features. It is not a fork of workspacer, and is built from the ground up.

It should be noted that workspacer is no longer in active development.

I am grateful to the workspacer project for the inspiration and ideas it has provided.

This is one of the key areas where Whim differs from workspacer.

Currently, workspacer stores all windows in an IEnumerable<IWindow> stack which is passed to each ILayout implementation. Relying so heavily on a stack prevents workspacer from supporting more complex window layouts. For example, Whim's TreeLayoutEngine uses a n-ary tree structure to store windows in arbitrary grid layouts.

Whim does not have a core concept of a "primary area", as it's an idea which lends itself to a stack-based data structure. However, it is possible to implement this functionality in a custom ILayoutEngine and plugin.

As Whim supports more novel layouts, it also has functionality to account for directions, like FocusWindowInDirection, SwapWindowInDirection, and MoveWindowEdgesInDirection. For example, it's possible to drag a corner of a window diagonally to resize it (provided the underlying ILayoutEngine supports it).

Implementations of Whim's ILayoutEngine should be immutable. This was done to support functionality like previewing changes to layouts before committing them, with the LayoutPreview plugin. In comparison, workspacer's ILayoutEngine implementations are mutable.

After cloning, make sure to run in the root Whim directory:

git config core.autocrlf true

Please file an issue if you find any bugs or have any feature requests. Pull requests are welcome.

Work is currently being tracked in the project board.

Before making a pull request, please install the tools specified in .config/dotnet-tools.json:

dotnet tool restore
# To run the formatters:
dotnet tool run dotnet-csharpier .
dotnet tool run xstyler --recursive --d . --config ./.xamlstylerrc

Tests have not been written for all of Whim's code, but they are encouraged. Tests have not been written for UI code-behind files, as I committed to xUnit before I realized that Windows App SDK isn't easily compatible with xUnit. I'm open to suggestions on how to test UI code-behind files.

To use your existing configuration, make sure to update the #r directives to point to your newly compiled DLLs. In other words, replace C:\Users\<USERNAME>\AppData\Local\Programs\Whim with C:\path\to\repo\Whim:

#r "C:\Users\dalyisaac\Repos\Whim\src\Whim.Runner\bin\x64\Debug\net7.0-windows10.0.19041.0\whim.dll"
#r "C:\Users\dalyisaac\Repos\Whim\src\Whim.Runner\bin\x64\Debug\net7.0-windows10.0.19041.0\plugins\Whim.Bar\Whim.Bar.dll"
#r "C:\Users\dalyisaac\Repos\Whim\src\Whim.Runner\bin\x64\Debug\net7.0-windows10.0.19041.0\plugins\Whim.CommandPalette\Whim.CommandPalette.dll"
#r "C:\Users\dalyisaac\Repos\Whim\src\Whim.Runner\bin\x64\Debug\net7.0-windows10.0.19041.0\plugins\Whim.FloatingLayout\Whim.FloatingLayout.dll"
#r "C:\Users\dalyisaac\Repos\Whim\src\Whim.Runner\bin\x64\Debug\net7.0-windows10.0.19041.0\plugins\Whim.FocusIndicator\Whim.FocusIndicator.dll"
#r "C:\Users\dalyisaac\Repos\Whim\src\Whim.Runner\bin\x64\Debug\net7.0-windows10.0.19041.0\plugins\Whim.Gaps\Whim.Gaps.dll"
#r "C:\Users\dalyisaac\Repos\Whim\src\Whim.Runner\bin\x64\Debug\net7.0-windows10.0.19041.0\plugins\Whim.LayoutPreview\Whim.LayoutPreview.dll"
#r "C:\Users\dalyisaac\Repos\Whim\src\Whim.Runner\bin\x64\Debug\net7.0-windows10.0.19041.0\plugins\Whim.TreeLayout\Whim.TreeLayout.dll"
#r "C:\Users\dalyisaac\Repos\Whim\src\Whim.Runner\bin\x64\Debug\net7.0-windows10.0.19041.0\plugins\Whim.TreeLayout.Bar\Whim.TreeLayout.Bar.dll"
#r "C:\Users\dalyisaac\Repos\Whim\src\Whim.Runner\bin\x64\Debug\net7.0-windows10.0.19041.0\plugins\Whim.TreeLayout.CommandPalette\Whim.TreeLayout.CommandPalette.dll"

// Old references:
// #r "C:\Users\dalyisaac\AppData\Local\Programs\Whim\whim.dll"
// #r "C:\Users\dalyisaac\AppData\Local\Programs\Whim\plugins\Whim.Bar\Whim.Bar.dll"
// #r "C:\Users\dalyisaac\AppData\Local\Programs\Whim\plugins\Whim.CommandPalette\Whim.CommandPalette.dll"
// #r "C:\Users\dalyisaac\AppData\Local\Programs\Whim\plugins\Whim.FloatingLayout\Whim.FloatingLayout.dll"
// #r "C:\Users\dalyisaac\AppData\Local\Programs\Whim\plugins\Whim.FocusIndicator\Whim.FocusIndicator.dll"
// #r "C:\Users\dalyisaac\AppData\Local\Programs\Whim\plugins\Whim.Gaps\Whim.Gaps.dll"
// #r "C:\Users\dalyisaac\AppData\Local\Programs\Whim\plugins\Whim.LayoutPreview\Whim.LayoutPreview.dll"
// #r "C:\Users\dalyisaac\AppData\Local\Programs\Whim\plugins\Whim.TreeLayout\Whim.TreeLayout.dll"
// #r "C:\Users\dalyisaac\AppData\Local\Programs\Whim\plugins\Whim.TreeLayout.Bar\Whim.TreeLayout.Bar.dll"
// #r "C:\Users\dalyisaac\AppData\Local\Programs\Whim\plugins\Whim.TreeLayout.CommandPalette\Whim.TreeLayout.CommandPalette.dll"

Visual Studio 2022 is the easiest way to get started with working on Whim. Check the following:

• The .NET Desktop Development workload is installed (see the Visual Studio Installer).
• The Configuration Manager is set to Debug and your target architecture (e.g. x64).
• Each project's platform matches the current target architecture.
• Whim.Runner is set as the startup project.
• The green Start arrow is labeled Whim.Runner (Unpackaged).

Recommended Extensions:

• CSharpier
• XAML Styler for Visual Studio 2022

The Whim repository includes a .vscode directory with a launch.json file. This file contains a Launch Whim.Runner configuration which can be used to debug Whim in Visual Studio Code. Unfortunately tests do not appear in Visual Studio Code's Test Explorer.

Tasks to build, test, and format XAML can be found in tasks.json.

To see the recommended extensions, open the Command Palette and run Extensions: Show Recommended Extensions.

IContext has an UncaughtExceptionHandling property to specify how to handle uncaught exceptions. When developing, it's recommended to set this to UncaughtExceptionHandling.Shutdown to shutdown Whim when an uncaught exception occurs. This will make it easier to debug the exception.

All uncaught exceptions will be logged as Fatal.