Madness Desktop

A GitHub Desktop fork wired into the madness_interactive workshop — multi-machine git coordination, composable git hooks, and live workshop todos, on top of the familiar Desktop git client. Built with Electron, TypeScript, and React.

Early build. macOS on Apple Silicon only, unsigned. Releases are cut by hand and trail the default branch; build from source for the newest code.

Getting it

With Homebrew (macOS 13+, Apple Silicon), install the latest release:

brew install --cask madnessengineering/tap/madness-desktop

The build isn't signed or notarized, so macOS blocks the first launch. Run xattr -dr com.apple.quarantine "/Applications/Madness Desktop.app", or try to open it once and click Open Anyway under System Settings → Privacy & Security.

Or build it from source:

git clone https://github.com/MadnessEngineering/madnessDesktop.git
cd madnessDesktop
yarn
make install      # production build, quits the running app, installs into /Applications

Your settings live in ~/Library/Application Support/Madness Desktop, outside the app, so reinstalling keeps them.

Keeping it updated

Homebrew: brew upgrade --cask madness-desktop.

From source, pull and rebuild:

git pull
make install

make install-app skips the build and just re-installs the last one (and refreshes the madhub link).

What makes it different?

Everything GitHub Desktop does, plus workshop coordination:

• Hook Loadouts — install and toggle bundles of git-hook scripts per repository from the UI. A thin .d/ dispatcher lets multiple scripts stack on the same hook without clobbering each other, and recent hook runs show up in a log in the Changes sidebar. Presets: mad-standard, deploy-enabled, desktop-dev, minimal.

• Claude Code hooks — Settings → Claude Code installs the workshop's Claude Code hooks in Minimal, Standard, or Full tiers, and uninstalls exactly what it added. Every tier names sessions and colors their prompt bar by project, so parallel sessions are easy to tell apart.

• MQTT integration — a hook script publishes each commit, with its active todo, to an MQTT broker, under a per-machine topic your own tools can subscribe to.

• Omnispindle todos — a live todo list from the Omnispindle MCP server in the Changes sidebar, plus a todo-prefix hook that stamps the active todo ID into your commit message.

• Exploded view — when a repository has no local changes, flip the page to an instruction-manual drawing of it: every folder a lettered part sized by weight, submodules as dashed crates, tool dot-folders set aside, and a materials list underneath — or, when the pane is wide enough, beside the drawing it labels, with the part cards spread across the full width below. Click a loose file to open it in your external editor, or right-click it to open it with the default program or in vim in the integrated terminal, reveal it in Finder, or copy its path. Step into a folder to take it apart too, or into a submodule to switch the app to it — and back out again from the breadcrumb. Paint marks where the work is, one amber side per part: your uncommitted changes (also reachable from the diff header while you have them), the last 100 commits' history, or submodules drifting off their pins.

• Subrepo tooling — submodules nest under their monorepo as collapsible folders, un-added submodules appear as "ghost" rows with one-click Add, submodule commit history shows up in diffs, and push/pull steps through each submodule before the parent.

  

• Madness Themes — a pack of custom color schemes with a picker in Preferences → Appearance and hotkeys to cycle through them.

• Auto-switch monitor — automatically focuses whichever repository just picked up new changes.

• madhub CLI — open, clone, group, and run submodule ops from the terminal.

The madhub CLI

Install it from the app menu: Madness Desktop → Install Command Line Tool… (symlinks /usr/local/bin/madhub).

Command	What it does
madhub	Open the current directory
madhub open [path]	Open the provided path
madhub add [path] -g <group>	Add the repo to the list and file it under <group> (created if new)
madhub clone [-b branch] [-g group] <url>	Clone a repo by URL or owner/name (e.g. torvalds/linux), optionally checking out a branch and filing it under a group
madhub sub <op> [path] [sub]	Submodule op: init, pull, push (repo-wide, or one <sub>); sync, rollback (need <sub>)
madhub foreach <cmd> [-r] [path]	Run a shell command across every submodule and print the combined output
madhub group <ls|create|rm> [name]	List, create, or remove custom groups
madhub fav [path]	Toggle the repo as a favorite

The Madness ecosystem

Madness Desktop is one node in a larger workshop coordination system — git events flow over MQTT to the Omnispindle MCP server and the Inventorium dashboard. See docs/ecosystem.md for how the pieces fit together and how to bring a new machine onto the broker.

Documentation

• Installation & data directories
• Authentication
• Submodules, repositories, and remotes
• Terminal, local AI, and Claude Code
• Interface: keybindings, themes, reflog, changes list
• Hook Loadouts
• MQTT integration
• The Madness ecosystem
• Known issues
• All docs

Building & contributing

To set up a development environment, see docs/contributing/setup.md. The .github/CONTRIBUTING.md guide covers the source layout, and the docs folder has the rest.

Found a bug or want to suggest something? Open an issue. The Code of Conduct applies to all project interactions.

License

MIT

The MIT license grant is not for GitHub's trademarks, which include the logo designs. GitHub reserves all trademark and copyright rights in and to all GitHub trademarks. GitHub's logos include, for instance, the stylized Invertocat designs that include "logo" in the file title in the following folder: logos.

GitHub® and its stylized versions and the Invertocat mark are GitHub's Trademarks or registered Trademarks. When using GitHub's logos, be sure to follow the GitHub logo guidelines.