Open-source project
Toxblh/MTMR avatar
Toxblh/MTMR

MTMR turns the Touch Bar into a JSON-configured button strip

🌟 [My TouchBar My rules]. The Touch Bar Customisation App for your MacBook Pro

4,357 stars241 forksSwiftMIT

At a glance

What is it?
Toxblh's MTMR is a macOS Touch Bar customizer whose entire layout lives in one JSON file, with native buttons, script-backed buttons and swipe gestures. The config model is the interesting part, and the gap between source activity and shipped binaries is the catch.
Who is it for?
Adopt MTMR if you own a Touch Bar MacBook Pro and want a strip layout defined by one editable JSON file at ~/Library/Application Support/MTMR/items.json, rather than by hidden app state you cannot diff or reproduce on a new machine. Skip it if your automation needs input events anywhere other than the Touch Bar, since the item types cover the strip and nothing above it, and skip it if you would rather grant no Accessibility permission at all.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 5 days ago.
What is it written in?
Mainly Swift, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • Toxblh/MTMR4,357 ★ · +16
Star history
Repository2026-09-232026-11-15
Toxblh/MTMR4.3k4.4k

16 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The whole layout is one items.json file

MTMR's layout is written by hand as JSON, though the README links a community visual editor, MTMR Designer. Preferences live in a single file at ~/Library/Application Support/MTMR/items.json, and everything on the strip, including the buttons Apple ships with, is an entry in that file. The preinstalled configuration ships with more or fewer buttons than most people want, which tells you the project expects you to edit it.

Each entry is a typed object. A hardware key such as escape or volumeUp is one line of type name. A live readout such as cpu or battery carries a refreshInterval. A group wraps several items so they can be bordered and titled as one block. A group lists its members in an items array, and the README adds a separate close button type for closing a group:

js
{
  "type": "group",
  "align": "center",
  "bordered": true,
  "title": "stats",
  "items": [
    { "type": "play" },
    { "type": "mute" }
  ]
}

That design has one clear consequence. You can diff items.json, keep it in a dotfiles repository, and rebuild the strip on a new machine by copying one file.

Native plugins versus shell and AppleScript buttons

MTMR splits its button types by where the work happens, and the split is the honest part of the design. Native plugins such as cpu, timeButton, battery, weather, currency, dock, dnd, darkMode, pomodoro and upnext are handled inside the app. Custom buttons can run AppleScript or shell scripts.

The cpu plugin is the clearest case. The documentation states it has lower power consumption and higher stability than the shell-based solution, and the shellScriptTitledButton example notes that the native cpu plugin runs better; that example ships a shell one-liner parsing top output for idle percentage. The native version is three lines of configuration:

js
{
  "type": "cpu",
  "refreshInterval": 3,
  "width": 80
}

The shell equivalent refreshInterval of 2 and spawns a pipeline per tick. On a strip that repaints constantly, the difference between an in-process readout and a forked shell matters more than it would in a menu bar.

Script buttons exist because the native set cannot cover everything you might want. appleScriptTitledButton runs AppleScript from a filePath, an inline string or a base64 payload, and can change its own icon if the script returns two values, a title and an image label declared in alternativeImages. shellScriptTitledButton runs a shell command and, if the command emits ANSI colour escapes, sets the button background from it.

Swipe gestures bind touch to a script, not to a system shortcut

Volume and brightness gestures can be enabled from the status bar menu under the MTMR icon. Two finger slides change volume, three finger slides change brightness. Those are conveniences wired to what the Touch Bar already controls.

Custom gestures use the swipe type and are where the project becomes a scripting host. A swipe carries a finger count of 2, 3 or 4, a direction, an optional minOffset threshold below which the gesture does not fire, and two optional script bodies:

json
"type": "swipe",
"fingers": 2,
"direction": "right",
"minOffset": 10,
"sourceApple": {
  "inline": "beep"
},
"sourceBash": {
  "inline": "touch /Users/lobster/test"
}

Both source fields are optional and both may appear in the same object. Note what minOffset buys you: a gesture that fires on stray touches can be given a distance floor before MTMR emits anything. You may create as many swipe objects in the preset as you want.

Accessibility permission gates the hardware keys

Installation is short. The README gives two routes: a .dmg from the GitHub download page, or a Homebrew cask.

bash
brew install --cask mtmr

The first run is where it gets interesting. On first install you have to grant MTMR access in Accessibility, reachable through System Preferences, Security and Privacy, the Privacy tab, then Accessibility. Without it, buttons such as Esc, Volume and Brightness do not work, because those keys are synthesized and macOS treats the synthesis as synthetic input that the app must be permitted to send.

This is the first thing to verify after launching. A strip that looks correct but silently ignores every hardware key is the expected failure mode of a skipped permission, and the visual result gives you no hint that anything is wrong. Two related requirements follow from the same design: the app sends synthetic keys and executes AppleScript, so it carries real permissions on a machine you also use for work.

Colour feedback works only through shell ANSI escapes

Several plugins change their own appearance with state: cpu shifts colour with load, nightShift and dnd reflect system state. For script buttons, the documented route is narrower and worth knowing before you build anything on it. The shellScriptTitledButton note says 16 colours is the only mode supported presently, and that buttons set their own background colour to the colour returned by the script.

That is a real constraint on what you can render. The mechanism is an ANSI escape emitted by the shell command, so truecolour output is not available, and colour has to be chosen from a fixed palette inside an escape sequence. The CPU example does exactly this: it computes a busy percentage with awk, then selects an escape sequence with threshold checks before printing.

The appleScriptTitledButton goes a different route for appearance, using a base64 image field plus an alternativeImages map keyed by label, with a refreshInterval of 1 second in the example. Two mechanisms, two different costs, and they are not interchangeable. A designer would pick one before writing the script, not after.

Every MTMR button is a stopgap over hardware Apple controls

The author wrote that he wanted MTMR because he liked BTT and a full custom TouchBar, his BTT preset. That sentence frames the audience precisely: people arriving from a preset culture, and the gap between a preset and a hand-written JSON file is where the friction sits.

The hardware limit matters more. The Touch Bar is a fixed strip, and MTMR decides what fills it. A group with a title and a border, a cpu button at width 80, and a run of single keys all compete for the same strip.

The other structural limit is what the item types can be. Types are a closed set: hardware keys, native plugins, media keys, two AppleScript buttons, two slider types, groups, close and swipe. Anything you want that does not map onto one of those has to become a shell or AppleScript command, which puts you back into the refresh cost and the 16 colour limit described earlier.

A build-side detail is worth knowing before you rely on a fix. The repository root carries build.sh, test.sh, an Xcode project and a file named TECHNICAL_DEBT.md, and the last push was on 2026-05-14, well after the most recent tagged build. Any fix you need may therefore exist only in the source tree.

Where BTT and the stock Touch Bar differ

The obvious comparison is BetterTouchTool, which the author names as the inspiration. In MTMR the strip is a document. You describe what each region contains and MTMR renders it.

That difference decides which one suits you. If you want a fixed strip layout that you can review as text, keep in version control and regenerate on a new Mac, MTMR's items.json is the more direct instrument.

MTMR's native plugins, including cpu, battery, weather, currency and upnext, are built in rather than assembled from scripts. If you only wanted a clock and a play key, built-ins remove the shell entirely. The stock Touch Bar remains the honest baseline for anyone who wants no permissions at all, at the cost of the buttons Apple decided to put there.

Editorial conclusion

Adopt MTMR if you own a Touch Bar MacBook Pro and want a strip layout defined by one editable JSON file at ~/Library/Application Support/MTMR/items.json, rather than by hidden app state you cannot diff or reproduce on a new machine. Skip it if your automation needs input events anywhere other than the Touch Bar, since the item types cover the strip and nothing above it, and skip it if you would rather grant no Accessibility permission at all. Verify first that the types you plan to write match the documented schema, that your layout actually fits the strip, and that any fix you need exists in a built binary rather than only in the source tree.

Frequently asked questions

What are some good apps for the MacBook Touch Bar?

MTMR is one, aimed at people who want the strip described by a JSON file at ~/Library/Application Support/MTMR/items.json. It offers hardware keys, native plugins such as cpu and weather, and script-backed buttons, and the author cites BetterTouchTool as his inspiration, saying he liked BTT and his full custom BTT preset.

How do I customize the Touch Bar on my MacBook?

With MTMR, install the .dmg from the GitHub download page or the Homebrew cask, grant it Accessibility permission, then edit ~/Library/Application Support/MTMR/items.json. Buttons, plugins, sliders, groups and swipe gestures are all declared in that file.

Which MTMR button type should I use for CPU load?

Use the native cpu plugin. The documentation states it has lower power consumption and higher stability than the shell-based shellScriptTitledButton example, which spawns a top and awk pipeline on each refresh.

Can MTMR show an icon that changes with a script result?

Yes, with appleScriptTitledButton. Declare the icon labels in alternativeImages, have the script return two values as {"TITLE", "IMAGE_LABEL"}, and make sure the returned label exists in alternativeImages.

Why do MTMR buttons like Esc and Volume do nothing at first?

MTMR needs Accessibility access on first install, granted through System Preferences, Security and Privacy, the Privacy tab, then Accessibility. Without it the synthesized keys that drive Esc, Volume and Brightness are ignored by macOS.

Can MTMR change a button's background colour?

For shellScriptTitledButton, yes, in 16 colour mode. The button sets its own background to the colour the script returns, and ANSI escape sequences from the shell command are the documented way to produce it.

Official sources

  1. License: MIT
  2. Project website
  3. README
  4. Releases
  5. Toxblh/MTMR on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/toxblh-mtmr.svg)](https://hysenlabs.com/projects/toxblh-mtmr)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/toxblh-mtmr.svg)](https://hysenlabs.com/projects/toxblh-mtmr)

Was this useful?