Free · open source (MIT) · macOS · for Herdr

Welcome to my herd.

Control your Herdr AI agents in a thumb tap.

Your AI agents work in parallel inside Herdr (external link), but you don’t. MouseHerdr puts every agent one thumb-tap away.

MouseHerdr is a free, open-source macOS app I “built” for the Logitech MX Master 4, and it now works with almost any mouse. Tap the haptic thumb pad, or press the scroll wheel on another mouse, and a wheel of your coding agents appears around your pointer. The ones waiting on you glow orange and sit closest. Read the question, answer it with one click, and get back to work without hunting through ten terminal windows.

  • macOS 13 or later
  • Apple silicon and Intel
  • MX Master 4, and almost any other mouse
  • Herdr for the agent features
  • Signed and notarized releases
Animated demo from the README: the agent wheel opens around the pointer, two orange wedges need attention, and a question bubble offers numbered answers that are clicked to reply.
The agent wheel, animated (sample data).

Watch the trailer

One shepherd, a herd of agents, and a theme song.

What it does

The slow part of running ten agents isn’t the agents. It’s you, tabbing through terminals to find the one that has been waiting an hour. MouseHerdr brings the waiting ones to your pointer.

  • Agent wheel

    Tap your thumb to see every agent around your pointer.

  • Answer in place

    The agent’s question pops up in the wheel; click an answer, or type your own.

  • Approve risky commands

    See the exact command and say yes or no from your thumb.

  • Jump to any agent

    Click its slice to open it in Herdr.

  • Feel it

    A knock in your thumb when an agent needs you, a pulse when one finishes.

And the mouse still does mouse things

  • Remap every button

    Shortcuts, apps, gestures and the thumb wheel.

  • Drag and snap windows

    Hold the thumb pad, move, let go.

How it works with Herdr

MouseHerdr doesn’t run your agents; Herdr does. MouseHerdr is a remote control on top: it asks Herdr’s own command-line tools what your agents are doing, and types your answers back for you.

A friendly note: I’m not affiliated with Herdr (or Logitech). I’m just a fan of Herdr who built MouseHerdr for my own workflow, using the tools Herdr gives everyone. — Roy

The Herdr pieces it uses

  • Herdr

    “the runtime your coding agents live on” · herdr.dev (external link) · GitHub (external link)

    Herdr keeps your agents’ terminals running and marks every pane working, blocked or idle, so you never hunt for the stuck one. It runs the agents you already use, such as Claude Code, Codex and Cursor.

  • herdr-core (hc)

    “terminals for coding agents” · GitHub (external link)

    The engine underneath: hc runs programs and coding agents in terminals that stay alive after you leave. It draws nothing; you use it from your shell, an agent, or your own app. MouseHerdr is one of those apps.

  • The Herdr desktop app

    “a desktop app for terminals and coding agents” · GitHub (external link)

    The window where your agents live, with a sidebar that shows which agents need you. Its shell installer also installs herdr-core, so installing the app gets you both.

What happens when you tap

  1. Look. MouseHerdr runs hc ls --json to list the live terminals and keeps the ones that are coding agents, each with its status: working, blocked, done, idle or error.
  2. Read. For each agent it runs hc get … --json for the title and status message. When an agent is blocked and needs you, it reads that agent’s screen with hc read to find the numbered choices of its question.
  3. Answer. Picking a choice presses that number in the agent’s terminal with hc keys. A typed answer first picks the question’s “Type something” choice, then sends your words with hc send. herdr-core delivers an answer once that agent’s terminal has had about 3 seconds without typing or pointer movement; the choice you clicked is blue while the answer is on its way and turns green once the agent has it.
  4. Jump. Clicking a wedge asks the desktop app to focus that agent’s terminal (herdr-app do agent.focus), then brings the Herdr window to the front.

Talking to Herdr is all local commands on your Mac and makes no network requests. Each command gets a few seconds to answer, so a missing or stopped Herdr simply shows up as a status on the Agents page, and the mouse features keep working without it.

In detail

The same features, spelled out from the README. The agent features need Herdr; the rest work on their own. Where they name the haptic panel, top button, gesture button or thumb wheel, they describe the MX Master 4.

Herdr agent wheel

  • Tap the haptic panel to see your agents in a wheel around the pointer; on another mouse (external link), press the scroll wheel. Agents waiting on you are orange, wider, and closest.
  • Aim at one and click its wedge to jump to it in the Herdr app.
  • You need not aim at all. The middle of the wheel, where the pointer rests as it opens, stands for one agent: the one that most recently started waiting on you, or else the latest one. If it is waiting, its question is already showing. Click the middle to open it.
  • To put the wheel away, right-click the middle, press Escape, or press the button that opened it again.
  • The most recently active agents come first. A busy agent says how long its turn has run (“working 5m”) and a quiet one how long ago it was active (“3h ago”). Quiet agents fade to grey and get thinner and shorter, so the busy ones stand out; point at one and it grows back.
  • Right-click a wedge to pin that agent: pinned agents stay near the front at full size. The Agents page has a pin button on each agent too.
  • A small pill on a wedge counts the sub-agents that agent has busy, as herdr-core reports them. A sub-agent gets a wedge of its own only when it is waiting on you.
  • Every agent gets a wedge. On a crowded wheel they all get thinner, and the one you point at grows wide enough to read. When a Herdr space has several sessions, each wedge also says what its session is about, and the Agents page can order the wheel by space instead.
  • If it asked a question, a speech bubble shows it. Each offered choice is a button you can click to answer without leaving what you’re doing; hovering a choice shows its explanation, and “Type your own answer…” opens a small text box.
  • When an agent asks to run something risky (“Do you want to proceed?”), the bubble shows the exact command and the agent’s own choices, such as Yes, Yes and don’t ask again, and No, so you can approve or refuse it from the mouse.
  • A knock in the thumb pad when an agent starts waiting on you, and a pulse when one finishes.

Button remapping

  • Assign any of the wheel click, top button, gesture button, forward, back and haptic panel to an action: back/forward, tabs, Mission Control, desktops, copy/paste, media keys, screenshots, lock screen, a keyboard shortcut you record, or opening an app.
  • The gesture button has five actions: click, and hold-and-move up, down, left or right.
  • The thumb wheel can scroll sideways (default) or control volume, tabs, zoom, desktops, or undo/redo.

Window dragging and snapping

  • Hold the haptic panel and move the mouse to drag the window under the pointer, whether or not it is the active one. Let go to drop it.
  • While dragging, push into a screen edge to snap: left or right for half the screen, the top for full, a corner for a quarter.

Haptic feedback

  • A bump when a dragged window reaches a snap edge or a gesture fires.
  • Optional: a tick when the pointer crosses into or out of a window, and a fainter one when it lands on something clickable.

Other mice

  • MouseHerdr works out which mouse is connected, whatever its make, and shows its name and picture on the Buttons page. It notices a mouse the moment it is plugged in or paired.
  • On every mouse except the MX Master 4, pressing the scroll wheel shows your agents, in place of a middle click. To get the middle click back or use another button, pick it on the Buttons page.
  • Back and forward buttons go back and forward, and can be given any other action.
  • A mouse with no spare button, such as Apple’s Magic Mouse or Microsoft’s Arc Mouse, is told so. Use Show Agent Wheel in the menu bar icon’s menu instead.
  • Each mouse keeps its own settings, and one mouse is followed at a time: an MX Master 4 whenever it is connected, otherwise a recognised mouse before an unknown one. Change… on the Buttons page lists the mice connected now and every model MouseHerdr knows; pick yours if MouseHerdr got it wrong.
  • Some 60 mice are recognised, from Apple, Logitech, Microsoft, Razer, SteelSeries, Corsair and others: see the list in the README (external link). A mouse that is not in the list still works, with a plain layout that fits the number of buttons it declares.

One window, four pages

  • Agents comes first: it lists your agents with what each is asking, lets you answer or open one, and has a button to show the wheel.
  • Buttons is the mouse picture for assigning actions, including “Show the agent wheel” for any button.
  • Feel holds the haptic and window-snapping switches.
  • Settings has the switches for starting at login and for automatic updates, with Check for Updates… and What’s New…. Beside the app’s name the window says which version is running.
The MouseHerdr window on its Agents page: two agents marked “Needs you” with their questions and numbered answer buttons, and the agent wheel settings on the right.
The Agents page (screenshot from the repository, sample data).
The agent wheel around the pointer: two orange “needs you” wedges at the top, others marked working, idle or done, and a speech bubble above with numbered answer choices.
The agent wheel with a question bubble and its answer choices (sample data).
The Buttons page: a drawing of the MX Master 4 with labels for the thumb wheel, gesture, forward, back, wheel click, top button and the highlighted haptic panel set to “Drag the window”, next to a list of actions; a card names the connected mouse, with a Change… button.
The Buttons page: pick a control on the mouse picture, then choose its action.

Who it is for

MouseHerdr is a focused tool: your Herdr agents, your mouse, one platform.

A good fit if you

  • run several coding agents in Herdr (external link) and want to see and answer them without hunting through terminals;
  • use a Logitech MX Master 4 over Bluetooth, or almost any other mouse with a wheel that clicks, with a Mac running macOS 13 or later;
  • want to remap an MX Master 4’s buttons without Logi Options+;
  • move and snap windows a lot and would rather do it from the MX Master 4’s haptic panel.

Look elsewhere if you

  • need the MX Master 4’s top button, haptics or battery level through a Logi Bolt or Unifying USB receiver: those work over Bluetooth only;
  • need every button of a mouse other than the MX Master 4: other mice get the wheel click and the back and forward buttons, and only the MX Master 4 has been tested on the device;
  • want haptic feedback from a mouse other than the MX Master 4: it is the only one whose haptic motor MouseHerdr drives;
  • want to keep running Logi Options+ at the same time: the two will fight over the buttons.

Requirements

Requires macOS 13 or later and a mouse: an MX Master 4 connected over Bluetooth gets every feature, and almost any other mouse gets the basics. Button remapping and window dragging work on their own; the agent features need Herdr (external link).

Mac
macOS 13 or later (developed and tested on macOS 26, Apple silicon). Release downloads run on Apple silicon and Intel; mouse hardware testing has been on Apple silicon, with an MX Master 4.
Mouse
A Logitech MX Master 4 connected over Bluetooth gets every feature. Any other mouse, over USB or Bluetooth, gets the basics (external link): pressing the scroll wheel opens the agent wheel, and the back and forward buttons can be given any action.
Permissions
Accessibility, and for the MX Master 4’s direct link Input Monitoring, in System Settings → Privacy & Security. Working out which mouse is connected needs neither.
To build from source
Xcode command line tools (Swift 5.9 or later). An Apple Developer account is not required.
For the agent features
Herdr (external link). Button remapping, window dragging and the other haptics work without it.

There are no required accounts or API keys. The one third-party Swift package is Sparkle (external link), which installs the updates.

Limitations and good to know

  • Only the MX Master 4 has full support: every button, the thumb wheel and the haptic motor. Other mice use what macOS reports for any mouse, the wheel click and the back and forward buttons; extra buttons that need the maker’s software are not available. Only the MX Master 4 has been tested on the device.
  • The MX Master 4’s top button, real hold and release on its haptic panel, haptics and battery level work over Bluetooth only. Through a Logi Bolt or Unifying USB receiver a mouse is seen as “a mouse on a receiver”, with its wheel click, back and forward buttons, until you pick its model.
  • New releases are Developer ID signed and notarized by Apple. Releases published before signing was enabled remain ad-hoc signed; when upgrading from one of those or from a source build, you may need to remove and re-add the Applications copy in Accessibility and Input Monitoring, because its signing identity has changed.
  • Signed releases check for updates daily and download them in the background. You can turn that off in Settings. Source and ad-hoc builds do not auto-update to public releases.
  • Running Logi Options+ at the same time will fight over the buttons. Use one or the other.
  • Remaps of the wheel click, back and forward apply to any mouse connected to the Mac: macOS does not say which mouse a click came from. MouseHerdr follows one mouse at a time and uses that mouse’s settings.
  • Quitting from the menu bar hands every button back to the mouse.
  • “Feel what’s clickable” asks each app what is under the pointer, which can slow Chromium-based apps slightly. Turn it off if you notice.
  • This is an independent project, not affiliated with, endorsed by, or supported by Logitech, Apple, Microsoft, Razer, any other maker of the mice it recognises, or Herdr. It sends commands to your mouse and presses keys on your behalf; use it at your own risk.

Install

Download the latest Mac app, or build it from source. Each release contains one app for both Apple silicon and Intel, and keeps itself up to date.

Download a release

  1. Download MouseHerdr.zip (external link) and unzip it.
  2. Quit any running MouseHerdr, then drag MouseHerdr.app to Applications. Replace the older copy if you are updating; your assignments remain saved.
  3. Open MouseHerdr from Applications. macOS may ask you to confirm opening an app downloaded from the internet.
  4. Grant Accessibility and Input Monitoring (see below), then quit and reopen MouseHerdr.

New releases are Developer ID signed and notarized by Apple, with the notarization ticket included in the app. Releases published before signing was enabled remain ad-hoc signed; check their release notes. When upgrading from one of those releases or a source build, you may need to remove and re-add the Applications copy in Accessibility and Input Monitoring because its signing identity has changed.

Verify the download

Save MouseHerdr.zip.sha256 (external link) from the same release beside the ZIP, then run this in that directory:

Check the SHA-256

shasum -a 256 -c MouseHerdr.zip.sha256

Automatic updates

Signed releases check for updates daily and download them in the background by default. When an update is ready, choose Restart to Update in the menu bar or Settings; it also installs when you next quit MouseHerdr. Your assignments and settings stay saved, and What’s New opens after the update with offline release notes.

In Settings, uncheck Automatically check for and download updates to stop the automatic checks and downloads; Check for Updates… remains for manual checks. Updates use Sparkle to verify the signed feed and the download before installing the signed app. Source and ad-hoc builds do not auto-update to public releases, and older releases without the updater need one manual download to get it.

Build from source

Install Apple’s command line tools if you have not already, check that swift --version reports Swift 5.9 or newer, then:

Build and install

xcode-select --install
git clone https://github.com/royosherove/mouse-herdr.git
cd mouse-herdr
./build.sh install

This builds the app, copies it to /Applications/MouseHerdr.app and starts it. The first start opens the window; after that it starts quietly in the menu bar and at login. You can turn off Start MouseHerdr when I log in in Settings.

Run the build as your normal user, without sudo; if Applications needs administrator approval, copy dist/MouseHerdr.app there with Finder and open it. Source builds use a local signing identity, so macOS keeps your permissions across rebuilds; they are not notarized by Apple and do not auto-update.

Update a source build

Keep the same checkout and its signing/ directory, then run:

Update

git pull --ff-only
./build.sh install

Grant permissions

In the app’s setup panel, grant these two permissions under System Settings → Privacy & Security:

PermissionWhy
AccessibilityTo press shortcuts for you and move windows. Required.
Input MonitoringTo talk to the mouse directly. Needed for the top button, real hold and release on the haptic panel, haptics, and battery level. Only asked for with a Logitech mouse on Bluetooth that has such buttons.

If MouseHerdr does not appear in the Input Monitoring list, click + there and choose it from Applications. Quit and reopen MouseHerdr after granting Input Monitoring, or use its relaunch button. Working out which mouse is connected needs neither permission.

Or let a coding agent build it

The README includes a prompt you can paste into an agent that can run commands on your Mac. It checks the toolchain, builds as your normal user with local signing, runs the tests, installs, tells you which mouse it found, and guides you through the permissions. Herdr stays optional. Copy it from Building from source for agents (external link).

Uninstall

Turn off Start MouseHerdr when I log in, then quit from the menu bar. Delete /Applications/MouseHerdr.app, ~/Library/Application Support/MouseHerdr and ~/Library/Logs/MouseHerdr.log, and remove MouseHerdr from Login Items and the two privacy lists. To also clear its UI preferences:

Clear UI preferences

defaults delete dev.mouseherdr.app

Source builds also have a signing identity to remove; see signing cleanup (external link) in the README.

Set up the agent wheel (optional)

Install the Herdr desktop app (external link) separately; its shell installer also installs herdr-core. Start the app and open a coding-agent session there. MouseHerdr uses the hc command from herdr-core to list agents and send answers; herdr-app and the desktop app are used to focus an agent’s terminal.

The app looks for these commands in ~/.local/bin, /opt/homebrew/bin, /usr/local/bin and ~/.cargo/bin. Check the connection without starting the mouse remapper:

Check the Herdr connection

/Applications/MouseHerdr.app/Contents/MacOS/MouseHerdr --herdr-status

The Agents page shows whether Herdr is missing, stopped, or running without agents. MouseHerdr rechecks while it runs, so installing or starting Herdr does not need a MouseHerdr restart.

Under the hood

A native Swift app (SwiftUI window, menu bar item); its one third-party package is Sparkle, for updates. The mouse side and the agent side are separate paths:

MX Master 4 Bluetooth HIDPP.swift HID++ 2.0: diverted buttons, battery, haptics ActionRunner.swift event tap: extra buttons, thumb wheel AppState.swift profile, actions, window drag and snap macOS key and media events, windows Agents.swift hc (herdr-core) ⇄ Herdr
Data flow: the MX Master 4 talks HID++ 2.0 over Bluetooth to HIDPP.swift; the ordinary buttons of any mouse and the thumb wheel reach ActionRunner.swift through an event tap; actions go out as key and media events; Agents.swift talks to Herdr through the hc command.

The source, file by file

HIDPP.swift
speaks Logitech’s HID++ 2.0 protocol over the mouse’s Bluetooth vendor channel: it captures (“diverts”) the buttons macOS never sees, reads the battery, and plays the built-in haptic waveforms.
ActionRunner.swift
watches the ordinary extra buttons and the thumb wheel with an event tap, and performs actions by posting key and media events.
MouseProfile.swift
describes what a mouse is: how to recognise it, its controls, where their presses come from, its defaults and its picture. In Profiles/, MXMaster4.swift is a mouse drawn and described by hand, Catalog.swift lists the other mice a line each, and Bodies.swift has the shapes those are drawn from.
MouseDetector.swift
lists the mice connected to the Mac, of any make, and hears them come and go. It reads what each device reports about itself without opening it, so it needs no permission. It also decides which one to follow and which profile it gets.
MouseSetup.swift and MousePicker.swift
decide what to say about a newly found mouse, and are the notice and the list of mice in the window.
AppState.swift
follows the chosen mouse, ties its controls to actions and holds the window dragging and snapping.
Feel.swift
has the hover and window-edge detection and the snap preview.
Agents.swift
reads agent state from hc (herdr-core), draws the wheel and speech bubble, and sends answers back with hc keys and hc send.
Updates.swift and UpdateViews.swift
hold the Sparkle updater and the Settings page.
MouseView.swift and ContentView.swift
are the SwiftUI window, drawn from the profile.

The default button map, in code

Everything specific to one mouse lives in a MouseProfile. These are the MX Master 4’s defaults, quoted from the profile source (external link): the haptic panel drags windows, the gesture button and its hold-and-move directions drive Mission Control, App Exposé and desktops.

Sources/MouseHerdr/Profiles/MXMaster4.swift, lines 56–68

defaults: [
    .middle: .standard,
    .modeShift: .standard,
    .thumbPanel: Action(kind: "dragWindow"),
    .thumbWheel: .standard,
    .back: Action(kind: "back"),
    .forward: Action(kind: "forward"),
    .gesture: Action(kind: "missionControl"),
    .gestureUp: Action(kind: "missionControl"),
    .gestureDown: Action(kind: "appExpose"),
    .gestureLeft: Action(kind: "spaceLeft"),
    .gestureRight: Action(kind: "spaceRight"),
],

Adding a mouse

First find out what the mouse reports: with it connected, MouseHerdr --detect-mice prints its vendor and product id, its name, how many buttons it declares, and the profile it gets now. A mouse with the usual buttons is one line in Profiles/Catalog.swift: its id, brand and name, the product ids or name parts it is recognised by, the body it is drawn from and its buttons. A mouse with a shape or controls of its own gets a file of its own: copy Profiles/MXMaster4.swift, set its productIDs and/or nameContains, list its controls (each with a slot, a source such as .button(n) or .hidpp(cid:), and where it sits on the picture), then add it to MouseProfile.all. Such a mouse is recognised, not tested, until it has been checked on the device. Check the drawing without the mouse:

Render a profile without the mouse

./build.sh
dist/MouseHerdr.app/Contents/MacOS/MouseHerdr --snapshot /tmp/mouse.png --profile <id>

Full steps: Adding a mouse (external link).

What the build script does

  • Builds with swift build and assembles dist/MouseHerdr.app.
  • Signs the app with a self-signed certificate it creates in signing/ (not committed), so macOS keeps your permissions across rebuilds. To make that certificate findable it adds that keychain file to your keychain search list. Keep the signing files private.
  • Uses the app identifier dev.mouseherdr.app. To customize the build, copy local.env.example to local.env and edit it. Keep your chosen identifier stable after granting permissions. local.env is ignored by Git and is sourced as shell code.
  • Verifies the app’s signature before installation and stops if any build step fails.

The whole of the optional build settings file:

local.env.example

# Optional build settings. Copy to local.env before editing.
# local.env is sourced as shell code: only use a file you trust.
# Keep the identifier stable after granting macOS permissions.
BUNDLE_ID=dev.mouseherdr.app

# local creates a persistent signing identity in the ignored signing/ directory.
# adhoc is for disposable test builds and CI; permissions may reset on rebuild.
SIGNING=local

Releases and tests

After CI passes for a push to main, the Release workflow publishes only when the app or its build inputs changed (Sources/, Resources/, Package.swift, Package.resolved, build.sh or VERSION). Documentation, tests and CI-only changes do not create releases.

It builds one universal app, signs it with Developer ID and has Apple notarize it, verifies both architectures and the extracted ZIP’s signature, runs the setup checks against the extracted app, then publishes MouseHerdr.zip, its SHA-256 checksum, and the signed Sparkle appcast.xml. The version is the contents of VERSION followed by the total commit count on main.

GitHub Actions runs the tests and packages an ad-hoc signed app on Intel and Apple silicon macOS runners. These checks do not validate Bluetooth hardware, privacy permission prompts or behavior on every macOS release.

Tests (CONTRIBUTING.md)

swift test
python3 scripts/test_release.py
python3 scripts/test_sign_release.py
python3 scripts/test_update_feed.py
SIGNING=adhoc ./build.sh
MOUSEHERDR_TEST_BINARY=dist/MouseHerdr.app/Contents/MacOS/MouseHerdr python3 scripts/test_setup.py

The HID++ feature and function numbers were learned from the documentation and source of Solaar (external link), the Linux device manager for Logitech devices. The device ids that other mice are recognised by were collected from the Linux kernel’s HID drivers, Solaar, libratbag, OpenRazer, rivalcfg, ckb-next and the USB ID Repository. No code from any of them is included.

Privacy

MouseHerdr has no telemetry. Remapping, window inspection and settings stay on your Mac.

The one thing it asks the network for is its own updates: a signed release checks GitHub for a new release daily and downloads it in the background, sends no profile of your Mac with the check, and stops when you turn automatic updates off in Settings. Source and ad-hoc builds do not auto-update.

With agent features enabled, it reads agent status, titles, questions and terminal text through the locally installed Herdr tools, and sends answers through those tools when you choose to reply. Herdr and your coding agents have their own network behavior.

To recognise a mouse, MouseHerdr reads what each connected pointing device reports about itself: its vendor and product ids, its name, how it is connected and how many buttons it declares. It opens none of them and sends nothing anywhere.

MouseHerdr does not read the keyboard, with one exception: while the agent wheel is showing, key presses pass through it so that it can tell when Escape is pressed and put the wheel away. It acts on no other key, keeps and logs none, and stops the moment the wheel closes.

Logs can contain application names, agent workspace/tab names, button events, local paths and the names of connected mice; a Bluetooth mouse’s name can include its owner’s. Typed answers are logged by character count, not their contents.

Settings are in ~/Library/Application Support/MouseHerdr: config.json holds the MX Master 4’s buttons, mice/ has a file for each other mouse, and mice.json remembers which mice have been met and what you picked for them. The log is at ~/Library/Logs/MouseHerdr.log.

FAQ

Is it free?

Yes. MouseHerdr is free and open source under the MIT License, and downloads come straight from GitHub releases.

Do I need Logi Options+?

No. MouseHerdr talks to the mouse directly. Running Logi Options+ at the same time will fight over the buttons, so use one or the other.

Which mice does it support?

Almost any mouse, over USB or Bluetooth. MouseHerdr was built for the Logitech MX Master 4, the one mouse it supports in full: every button, the thumb wheel and the haptic motor. It also recognises some 60 other mice from Apple, Logitech, Microsoft, Razer and others, and a mouse that is not on its list still works, under the name it reports.

On every mouse except the MX Master 4, pressing the scroll wheel opens the agent wheel, and the back and forward buttons can be given any action. A mouse with no spare button, such as Apple’s Magic Mouse, uses Show Agent Wheel in the menu bar icon’s menu instead. Only the MX Master 4 has been tested on the device; the README lists the mice MouseHerdr recognises (external link).

Does it work with the Logi Bolt receiver?

For the basics. Through a Logi Bolt or Unifying USB receiver a mouse is seen as “a mouse on a receiver”, with its wheel click, back and forward buttons, until you pick its model on the Buttons page. The MX Master 4’s top button, haptics and battery level need Bluetooth.

Does it run on Intel Macs?

Release downloads run on Apple silicon and Intel. It is developed and tested on macOS 26, Apple silicon, and mouse hardware testing has been on Apple silicon, with an MX Master 4.

Is the app signed and notarized?

New releases are, yes: Developer ID signed and notarized by Apple, so macOS only asks you to confirm opening an app downloaded from the internet. Releases published before signing was enabled remain ad-hoc signed, and source builds use a local signing identity and are not notarized.

How does it update?

Signed releases check for updates daily and download them in the background. When one is ready, choose Restart to Update in the menu bar or Settings, or just quit: it installs then. You can turn automatic updates off in Settings and use Check for Updates… instead. Source builds update with git pull --ff-only and ./build.sh install.

Do I need Herdr?

Only for the optional coding-agent features. To use MouseHerdr without Herdr, turn off the thumb-pad tap and agent haptics on the Agents page; the mouse controls, window dragging and other haptics work separately.

What happens when I close the window or quit?

Closing the window leaves remapping running; click the mouse icon in the menu bar, then Open MouseHerdr… to get it back. Quitting from the menu bar hands every button back to the mouse.

The buttons do nothing. What should I check?

Grant Accessibility to the copy in Applications, and quit other mouse remappers, including Logi Options+. If the top button, haptics or battery are unavailable, connect over Bluetooth, grant Input Monitoring, then relaunch MouseHerdr.

Why does my wheel click no longer middle-click?

On a mouse other than the MX Master 4, the wheel click opens the agent wheel. On the Buttons page select Wheel click and choose Mouse default, then give the agent wheel to another button if you like.

It shows the wrong mouse, or none. What now?

On the Buttons page choose Change…, then your mouse under Connected now or your model in the list. A mouse on a USB receiver does not say what it is, so it gets a plain picture until you pick its model. A trackpad is not counted as a mouse.

Is it made by Logitech or Herdr?

No. It is an independent project, not affiliated with, endorsed by, or supported by Logitech, Apple, Microsoft, Razer, any other maker of the mice it recognises, or Herdr.

How do I report a bug or contribute?

Use GitHub issues (external link) for bugs and suggestions, and pull requests for changes; see CONTRIBUTING.md (external link). For a vulnerability, follow SECURITY.md (external link). For a bug report, include your macOS version, Mac architecture, mouse model, connection type, swift --version, the output of --detect-mice, and the relevant error.

Share the herd

Know someone with ten agents and one pair of eyes? Here’s the short version.