Checkpoint System: An Additional Way to Debug in KM

Hi all,


If you dislike debugging in KM then there is a new utility waiting to make your life less stressful... now go to the How Do I Get It? section at the end. If you have a few minutes - keep reading!

There is one thing I do not enjoy about KM.

Debugging :bug:

In fact, I can see from the forum that some other users feel this way too.

I've now been using KM since beginning of 2014 and while my knowledge of KM and skill at constructing macros has increased and improved from the beginning, my debugging skills have remained more or less at a standstill.

This is not meant to be a criticism of KM - which I love - but more a reflection on the "visual programming" paradigm that presents obstacles to reading, structuring, maintaining and debugging code.

Virtually all of my debugging activities involve adding Display Text or Notification actions at strategic points around my macros to see what is happening with my variables and what path is being taken through the macro logic. Then on discovering something, I have to add more Display Text actions, remove existing ones and try again - hoping for the best.

And then, while the macro's running, all these Display Text windows pop up and hang around and obscure what's going on behind them and heaven forbid that I want to do some GUI manipulation at the same time!

Using notifications is unhelpful - they just don't display enough information. And neither does the in-built KM debugger - it really doesn't show the information I need to see and I personally have a lot of trouble getting it to work.

It all really is difficult, tedious and tiresome for me. Hey - the time I save automating tasks with KM is sometimes almost negated by the time I spend setting up and doing debugging!

So I decided to do something about it.

I developed the Checkpoint System .

What is the Checkpoint System?

It's a tracing/breakpointing system that lets you

  1. observe any variables and values in your macros that you want in real time ;
  2. start/stop macro execution at points you determine;
  3. see the path taken through nested macros and submacros (breadcrumb trail );
  4. record all this stuff in a log file that is also optionally on display and updated in real time for detailed analysis.

How does it work?

The Checkpoint System is implemented as follows:

  1. Three KM plug in actions that do all the hard work for you.
  2. A set of utility macros accessed through a simple menu to make using the Checkpoint System even easier.

In addition it comes with:

  1. Comprehensive documentation.
  2. Demonstration macros to help you get started.

How is it different to the built-in debugger?

  1. You can use the Checkpoint System in "headless mode" which allows the correct operation of GUI-related macros and does not get in the way of them but still records everything in the log file so you can later analyse what went on.
  2. You can choose precisely the granularity and level of detail you want to see.
  3. You can have visibility over all variables - global, instance and local.
  4. It provides single mouse-click control over the scope of tracing/breakpointing.
  5. It's pretty intuitive to use.

Who's it for?

You might consider using the Checkpoint System when your macro isn’t working as you expect and the macro:

  1. manipulates/changes data and you’re unsure about how/what it is actually doing with the data;
  2. gets data from various sources and you are not confident that the right data is being obtained;
  3. calls (executes) other macros;
  4. has many actions;
  5. has many “decision” points – such as If…Then actions, for example – meaning the logic in it is complicated;
  6. keeps misbehaving and you’re tired of putting Display actions in your macro and dealing with multiple display windows that get in the way, or even missing display notifications that disappear too quickly and don’t show all the information.

Or you might just want a quick, easy and flexible way to look at the variables in your macro.

How Do I Get It?

The Checkpoint System consists of both third party plug ins and KM macros and you need to follow the instructions in the User Guide to install it properly. It's not hard to do, but it's not just a double-click either.

Here is the User Guide:
Checkpoint for Keyboard Maestro - User (1.2 MB)

Download it and then unzip it. Read it through and if you think the Checkpoint System is something that you could use, just send me a Private-Message asking for it and I'll send you the installation file.

Before you ask why this way - here's the answer: I'm doing it this way because

  1. I want to know how many KM users have the Checkpoint System
  2. I want to minimise the time I spend on support

I hope you've found this interesting!


magnificent, does it come with a macro example?
Can you send DM with link, thanks

1 Like

Yes - I provide straightforward examples and walk through them in the user guide so you can see how to use it.

In my OP I asked you to DM me to avoid cases like yours, where your profile is hidden and prevents anyone DMing you! Looking forward to that DM from you...


I'm interested ! your profile is hidden, I can't access the message icon to send you a DM...

Check your private messages...

1 Like