MACRO: A Macro to Track Macro Usage

I know Keyboard Maestro has some built-in usage tracking, and you can easily view your macros sorted by use order. But you can't see the actual counts in the sorted view; you have to use the inspector to see the count for a particular macro. It also tracks everything, all the time, and can't be reset (I don't think).

I wanted a tool that I would show all my macro usage in one report, that I could use to only track macros I wanted to track, and that would be easy to reset if I decided to do so (or, you know, had to do so during development because I did something stupid).

I decided to write my own simple tracker—mostly because I wanted the data to help thin my collection and see which macros I use the most, but also just to see what was possible.

__ Macro Usage Counter 3.4 Macros.kmmacros (242 KB)

Version 3.4 (Jan 12 2024): Changed update routine to only show a notification if there's a new version available.

Older versions

Version 3.3 (Dec 7 2023): Again with thanks to @cherry, an error that would double-count macro usage under some situations has been found and fixed.

Version 3.2 (Dec 6 2023): Thanks to @cherry, I found and fixed a fundamental issue: The tracking macro was calling the wrong tokens! This would lead to a double count and a missed count if you ever called the tracker from a main macro, and then again from a sub-macro called by the main macro.

Please update to 3.2, and replace all calls to the tracker with the action in this version of the macro. I am so sorry!

Version 3.1 (Dec 5 2023): Fixed an oversight in my logic that prevented the reporter from updating before there were 15 rows to process.

Version 3.0 (Dec 5 2023): This is basically a total rewrite of everything other than the report screen. The macro now uses a database, which is a great improvement over large global variables. It's faster, harder to mistakenly delete, and easier to back up. When I first wrote this, I didn't know how to use mysqlite3 databases with Keyboard Maestro, which is why I used global variables. Now that I know, this is how this macro should've been written from the start.

Existing users, if there are any of you out there, the macro should see that you're an existing user and migrate your data to the database. Just to be safe, keep version 2.4 around, and make a copy of the data in any rg_MacroUsageCounter... variables before you run the new version. (I upgraded two separate Macs, and both went well.)

2.4 update (Oct 7 2023): Fixed an issue in the back up and restore routines that affected their ability to back up and restore. Whoops.

2.3 update (Mar 29 2023): Added a new macro (in the Tools section) to reset all tracking data, and fixed a couple of bugs.

2.2 update: When usage counts exceed 1,000, they now get a comma in their displayed values. Also, and maybe more interesting, you can now live-sort any of the columns in the usage report.

2.1 update: A much-improved update routine (just run the update macro when you want to check), and a new framework that will verify in-macro updates, starting with the next update. Plus a reorganization of the macros in the macro group.

2.0 update: This is a total rewrite so that there's no background processing ever, and it works via a single "append to variable" action you insert in each macro. The work happens when you ask to see the report, which is (doh!) how I should have written it the first time.

1.1 update: I forgot to filter some variables that were used in regex searches to be regex safe. I warned you it was beta! If you installed the macro already, you can force an update check by deleting the global variable rg_MacroUsageCounter_lastchecked.

It's a very simple tracker—launch a macro, and the counter is incremented by one. But it does have some useful features…

  • Built-in backup and restore feature.
  • The report, as seen above, can be live filtered by typing in the box at the top. If you click on a row that you highlight with your mouse, you'll jump directly to that macro in the Keyboard Maestro editor.
  • Includes a macro that inserts the tracking macro action into your macros.

To use it, download the macro and install it, then activate the macro group. There's a "read me first" macro with some additional details, but to start using it, here's all you'd need to do:

  1. Open the macro named •main-user | 01 Insert tracking macro call and add the red-colored action to any macro you wish to track. The macro explains two ways to do that.
  2. Do your normal macro stuff. Each macro that has the action added will now start collecting data. The data won't be processed until you ask to see the report, so there's no overhead at all.
  3. Run the •main-user | 03 Show usage report macro. This will then walk through the database setup, and import any tracked macros into the database. (It will also import the old variable-based tracking data into the database, if you used a version of Macro Usage Tracker prior to 3.x.

I'd love feedback on this—it turned out nicer than I thought it would, and I'm finding it very useful. (Especially being able to jump right to edit mode from the report; that's a nice timesaver!) It should be safe to use, as it doesn't modify any existing macros unless you add its activating action to your own macros. You can disable the backup and update macros if you wish, as they're independent of the counter macro.



Looks pretty cool! I don't have time to try it out right now, but I know what it's like to post a new macro and not get a lot of feedback, so... :slight_smile:

1 Like

Thanks Dan—though if I really wanted more feedback, not posting at 5pm west coast time would probably help too :).


Actually, there are a lot of people overseas on this forum, so you'd be surprised. :slight_smile:

I've reposted the macro, and updated the text above to reflect the changes in this new version. It not only solves the update issues, but makes this a near-zero-overhead usage tracker—it only does the work when you ask to see the report.


1 Like

This looks intriguing. I’ll take a look at it tomorrow. Thanks for sharing!

2.1 is out now, linked above. Improved update mechanism and a framework for verifying future updates.


1 Like

2.2 is out, linked above, or check for updates from within 2.1. One new feature (the table columns are now sortable) and one enhancement (values over 1,000 are now comma-separated).



I love all the work that you put into this awesome macro! However, I can't seem to get it to run, even after reviewing all instructions provided. I've attached a screenshot of the error message that comes up when I attempt to run the report:

Any insight into what I'm doing wrong? Thanks in advance.

It's hard to tell specifically from that error message, but it clearly can't find something it's expecting to find. If you add a debug step to the main macro, you should be able to pinpoint the exact point where it fails as you step through it. That should be enough detail to figure out what's wrong.


[SOLVED] Thanks for the debugging tip. Turns out it was failing due to the first action below the first comment ("Update the Counters Before Displaying Report").

Once I disabled that action, it ran like a charm. Thank you for putting this macro together!

Revisiting this many months later…oops, that was a bug! It was failing because the execute macro command was set to "none." I'll be releasing an update shortly with that fixed, but in the interim, just enable that action again, click the "None" pop-up, and select "31] Process tracked macros" and it should work.

Sorry about that!



A tool that gives me more info about macro usage is exactly what I've been looking for.

It didn't work for me at first, but when I changed the "update the counter before displaying report" to execute macro 31] process tracked macros instead of "none" it worked.

However, if I want to reset the use count of all my macros, how do I do that? Deleting the macro and adding it back in changes nothing and I'm not clever enough to figure out where this persistent variable is stored.

Hmm, I thought I had that fixed in 2.2; guess I'll have to distribute a 2.3 to be sure—thanks!

Resetting is, right now, a manual proces, but pretty simple:

  1. Delete these two global variables: rg_MacroUsageCounter and rg_MacroUsageCounter_backup
  2. In Finder, press Shift-Command-G and enter /tmp as the folder name. Find and delete the file named rg_MacroUsageBackupFile.txt

That's it, everything should be zeroed now. Maybe I'll add an in-macro reset option, given I have to release a 2.3 anyway.


Macro Usage Counter 2.3 is out now; see the first post here for the download link if you don't have it already, or just run the 02] Check for update macro to force the update if you already have it installed.


This is very cool, thank you for posting it

Macro Usage Counter 2.4 is out and linked above, or if you check for updates it should show as available.

The only change is a fix for a glitch (i.e. my mistake) in the back up and restore macros that meant they weren't quite doing what I thought they were doing.


1 Like

Version 3.0 is out now, and linked in the first post. This is a total rewrite, as Macro Usage Counter now uses a database to store its data: No more relying on huge global variables that took up RAM and were way too easy to delete.

Existing users (if there are any out there :)) can run the check for updates macro, or just download it from the link in the first post.



Hello rob, Thanks for this macro. I bet the Stats-thirsty guy inside of me will want to know which macro I ended up using the most!

This is the first time I am using it so I downloaded V3.0. No prior setup.

I put the red macro action in my simple Page Up keystroke:

I ran this a few times and then try to generate the report. All I get is a blank screen:

(I believe I have set this up properly, so maybe I am missing something?)

It also looks like the sqlite is setup properly in the selected directory:

Any insights is appreciated!

I'm sure you have it set up right, too. I found a small glitch in my code: You won't see the report until you reach 15 entries. I just released 3.1 to fix that issue—check for updates to see it, and it'll be in the first post here in a minute.


1 Like