MTMR: Replacing the MacBook Pro Touch Bar with a JSON File

The Touch Bar Apple shipped and the one MTMR draws

Apple's default Touch Bar shows whatever the focused app decides to put there. There is no user-level file that says which buttons appear. MTMR takes that decision away from the app and puts it in a JSON document on disk, then renders its own strip on top. The README states the idea directly: "My idea is to create a platform for creating plugins to customize the TouchBar."

The audience is narrow and specific. You need a MacBook Pro with a Touch Bar, macOS 10.12.2 or later per the README badge, and a willingness to hand-write or hand-edit a config file. Anyone who wants a graphical settings window will be disappointed, though the README points to a third-party web editor, MTMR Designer, hosted on GitHub Pages by a contributor. The project also maintains a separate preset repository, MTMR-presets, where users share their `items.json` files, so a new user can start from someone else's layout instead of a blank file.

How the items.json config becomes Touch Bar widgets

The whole app is driven by one file: `~/Library/Application\ Support/MTMR/items.json`. The README says the pre-installed configuration "contains less or more than you'll probably want," which is a fair warning that you will be editing it.

Each entry in that file is an object with a `type` field. The README groups the built-in types into categories: plain buttons (escape, brightnessUp, volumeDown, mute, exitTouchbar), native plugins (timeButton, battery, cpu, currency, weather, inputsource, music, dock, nightShift, dnd, darkMode, pomodoro, network, upnext), media keys, AppleScript plugins (sleep, displaySleep), and custom buttons. Sliders are their own types: brightness and volume.

The custom button types are where the architecture shows. `staticButton` is a label. `appleScriptTitledButton` runs AppleScript on an interval and uses the returned string as the title. `shellScriptTitledButton` does the same with a shell command. The README notes that shell script output can carry escape sequences to set a background colour, and that "16 Colors" is the only mode supported presently, so a script returning a 256-colour code will not render as intended.

Scripts can come from three sources: `filePath`, `inline`, or `base64`. The README shows all three in one example. There is also a refresh mechanism: `refreshInterval` is optional on the AppleScript button and is measured in seconds, with the README's icon example using `refreshInterval: 1`. A button that polls every second is a button that runs a script every second, and the README does not discuss what that costs.

Installing MTMR and replacing one button

The README gives two install paths. Download the latest `.dmg` from the GitHub releases page, or use Homebrew. The cask name is given as `mtmr`.

brew install --cask mtmr

After installing, the README is explicit about one step that is easy to skip: "On first install you need to allow access for MTMR in Accessibility otherwise buttons like Esc, Volume, Brightness and other system keys won't work." The path it gives is System Preferences, then Security and Privacy, then the Privacy tab, then Accessibility, then MTMR. On current macOS the System Preferences app is named System Settings, but the Accessibility pane is in the same place.

To change a button, open the config file. The README stores it under Application Support with an escaped space in the path.

open ~/Library/Application\ Support/MTMR/items.json

Inside, a minimal button looks like this. The README shows `staticButton` with a `title` field, so a literal `esc` label is the smallest edit you can make.

{
  "type": "staticButton",
  "title": "esc"
}

Save the file and MTMR picks up the change. If you want a button whose label comes from a command, `shellScriptTitledButton` takes a `source` object with an `inline` script, the same shape the README uses for AppleScript. The README does not document a reload command or a menu item for forcing a re-read, so the assumption that edits apply on save is inferred from how the app is described, not from an explicit statement.

Gestures, and where the documentation stops

MTMR also listens for finger swipes on the Touch Bar itself. The README says basic gestures can be enabled from the status bar menu: two fingers for volume, three for brightness. Custom gestures use a `swipe` type with `fingers` (2, 3 or 4), `direction` (right or left), an optional `minOffset`, and optional `sourceApple` or `sourceBash` objects holding `inline` scripts. The README says you can add as many `swipe` objects as you want.

This is the part of the project I would treat with the most caution. The README describes `minOffset` as "optional: minimal required offset for gesture to emit event" but never says what unit it is in, and the example value is 10. There is no guidance on what happens when a two-finger swipe conflicts with a slider drag. The example scripts in the README are `beep` and `touch /Users/lobster/test`, which tells you the feature exists but not how it behaves under a real workload.

The same thinness applies elsewhere. The README lists `upnext` as a calendar plugin but does not say which calendars it reads or how permissions are granted. It lists `currency` and `weather` without naming the data source. For a project whose selling point is a config file, the config reference is a list of type names rather than a specification.

Release cadence and what that means for macOS updates

The last release listed is v0.27.0, dated 2020-11-20. The repository is not archived, and the last push was on 2026-05-14, so commits have landed since the last tagged release, but nothing has been published as a downloadable version in roughly six years. That gap matters more than usual here, because MTMR depends on private Touch Bar APIs and on Accessibility permissions, both of which Apple has changed across macOS releases.

The README badge says macOS 10.12.2 is the minimum. It says nothing about a maximum, and it does not document which macOS versions the current source builds against. A user on a recent macOS who installs the 2020 `.dmg` is running a binary compiled before several OS releases. The `build.sh` script and the Xcode project in the repository suggest you can build from source, which is the more plausible path on new systems, but the README gives no build instructions and no statement about supported Xcode versions.

There is a file in the repository root named `TECHNICAL_DEBT.md`. Its contents are not reproduced in the README, so I cannot say what it lists. Its existence is itself informative: the maintainers track known debt in a dedicated file rather than in the README.

Where MTMR is the wrong choice

Two failure modes are worth stating plainly.

First, if your Mac has no Touch Bar, MTMR has nothing to draw on. The README's own framing is MacBook Pro hardware, and the built-in button list is entirely system keys and Touch Bar affordances. There is no fallback to the menu bar, no on-screen equivalent.

Second, if you need the Touch Bar to keep working after an OS update without you thinking about it, MTMR is a poor fit. A project whose last published release is from 2020 and whose core mechanism is drawing into a system surface is exposed to every change Apple makes to that surface. The absence of any version compatibility statement in the README means you find out by installing it.

There is also a subtler cost. Every `appleScriptTitledButton` with a `refreshInterval` runs a script on a timer, and the README's own example sets that to 1 second. A layout with several such buttons is a layout that spawns processes continuously. The README does not warn about this, and there is no documented cap on how many buttons you can place.

MTMR against BetterTouchTool

The README names the alternative itself: "I very much like BTT and having a full custom TouchBar (my BTT preset), and I wanted to create it." BTT here is BetterTouchTool, a long-running commercial macOS utility that also customises the Touch Bar among many other input devices.

The difference is in approach, not just in features. MTMR is a single-purpose, MIT-licensed Swift app whose configuration is a JSON file you own and can commit to a repository. BetterTouchTool is a broader paid product with a graphical configuration interface covering trackpad, keyboard, mouse and Touch Bar together. If you want your Touch Bar layout version-controlled and shared as a file, MTMR's model is the one that fits, which is exactly why the project maintains a separate preset repository. If you want to configure gestures across several input devices in one place, or you want a vendor actively shipping updates against current macOS, MTMR is not that.

The licence difference is worth noting separately. MTMR is MIT, so you can read it, fork it and ship a modified build. BetterTouchTool is closed and paid. For a tool that sits this close to the OS, the ability to read and patch the source is a real advantage when something breaks.

Licence, maintenance and upgrade cost

MTMR is MIT licensed. That permits commercial and private use, modification and redistribution, provided the copyright notice and licence text are retained. It does not grant rights to Apple's Touch Bar APIs, and it does not change the fact that the app requires an Accessibility permission grant from the user. This is a description of the licence text, not legal advice.

Upgrade cost has two components. The first is the app itself: the last tagged release is v0.27.0 from 2020-11-20, so "upgrading" may mean building from source with the Xcode project and `build.sh` rather than replacing a `.dmg`. The second is your config. Because `items.json` lives in Application Support and is not versioned by the app, an app update will not migrate it, and the README does not describe any migration path. Back the file up before you touch anything.

Contributions are channeled through Discord and Telegram links in the README, plus a Travis CI badge for the master branch. There is no documented release schedule, and the gap between the last release and the last commit is the clearest signal of what to expect.

Editorial conclusion

MTMR fits MacBook Pro owners who are comfortable editing JSON and want system keys, sliders and script-driven buttons on the Touch Bar. It is not for anyone on a Mac without a Touch Bar, since that is the hardware it draws on. Before adopting it, check that the Homebrew cask still resolves and that a config written against the 2020 built-in button list is what you actually want, because the last release predates most current macOS versions.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. Toxblh/MTMR on GitHub