The Main Window for Debugging AutoHotkey Scripts

How to View the Inner Workings and Hidden Mechanisms of Running AutoHotkey Scripts

AutoHotkey includes a tool called the Main Window which aids with the debugging process. It gives you a peek into various aspects of a running .ahk script:

  1. Most recently executed lines of code (ListLines command).
  2. Current variables and values (ListVars command).
  3. Active Hotkeys (ListHotkeys command).
  4. Keyboard activity (KeyHistory command).

Main Window Menu

Open the Main Window by right-clicking on Windows System Tray icon of an active .ahk script and selecting Open from the top of the menu. The window pops open at the “Lines most recently executed” view. You can select the other three views plus “Refresh” from the View menu.


You’ve probably encountered the Main Window while writing scriptsif only through curiosity. When you look up Main Window online, you won’t find a direct reference—but, you will find pages for the four related commands (ListLines, ListVars, ListHotkeys, KeyHistory) each of which opens a specific Main Window view for a running script.

The Open option only appears in the AutoHotkey icon right-click menu for .ahk files—not compiled .exe files. However, the individual commands work in a script for both .ahk and .exe files. The key difference between using the Main Window commands in .ahk files and .exe files affects the View menu where AutoHotkey disables all options (except Refresh) for .exe files.

If you have trouble figuring out the source of problems in a script, the Main Window might just give you the help you need. The tool offers four types of insights.

ListLines Main Window Command

Whether you select “Lines most recently executed” from the View menu or insert the ListLines command into a script, a window pops open displaying the most recently executed lines of code. This may give you the best look at the activity occurring inside running a script.

Main Window Code
The ListLines view displays the most recently executed lines of code in a script.

This peek at the code allows you to determine if the proper lines run at the right time. For example in the InstantHotkeyLoop.ahk script, the first time (IH_Count = 1) you set up a new Instant Hotkey, it makes adjustments to the System Tray menu (as shown by ListLines):

098: if IH_Count = 1
100: Menu,Tray,Add,Instant Hotkeys,:HotkeyMenu
101: Menu,Tray,Insert,Instant Hotkeys,Add Text,:InsertText
102: Menu,Tray,Icon,Add Text,InstantHotkey.ico,1
103: }
105: Gui,Show,,Instant Hotkey %IH_Count% (0.23)

After this first instance (if IH_Count = 1), the script skips the Menu commands:

098: if IH_Count = 1
105: Gui,Show,,Instant Hotkey %IH_Count% (0.20)

This glimpse at the running code acts as a quick check on whether or not the If conditional worked in the designed manner.

At times while debugging a script, I would place a MsgBox command inside a conditional, loop, or function to check its operation. Although I find occasions where I still need to add my own checks to a script, often the ListLines view of the Main Window saves the extra work.

ListVars Main Window Command

Whether you select “Variables and their contents” from the View menu or insert the ListVars command into a script, a window pops open displaying the script variables.

Main Window Variables
The ListVars view displays script variables. To display Local variables, insert the ListVars command or another “pause” type command (e.g. MsgBox) inside the function.

While in most script debugging, the ListVars window might give you all that you need, you’ll find a couple of situations where AutoHotkey requires adding a trap into your code.

First, Local function variables only show up in the Main Window if you catch script processing while inside the function. That means you need to add either the ListVars command or a script pausing command (such as MsgBox) inside the function to see the Local variables in the Main Window at processing time.

Array HotkeysSecond, associative arrays only display the last value called, while pseudo-arrays, such as those shown in the image above (e.g. InstantHotkey1 and InstantHotkey2), display all the variable values. For example, since I could not view all the associative array values through ListVars in the Main Window, I added a Hotkey which displays all array values (as shown at right) to the InstantHotkeyArray.ahk script.

In spite of the quick variable info offered by the Main Window, you’ll find times when you need to add your own debugging traps while developing new AutoHotkey scripts.

ListHotkeys  Main Window Command

Whether you select “Hotkeys and their methods” from the View menu or insert the ListHotkeys command into a script, a view pops open displaying the script Hotkeys.

Main Windows Hotkeys
The ListHotkeys view shows all active Hotkeys in the script.

I rarely examine Hotkeys, but when I explored the “Secret Hotstring Trick” a few weeks ago, I needed to know whether or not AutoHotkey had installed the Keyboard Hook for target Hotkeys. Fortunately, while the Main Window does not supply that type of information for Hotstrings, it does for Hotkeys:

k-hook           #z
k-hook           #z
reg              !,
m-hook           XButton1
reg              ^6

Hotstrings can’t launch Hotkeys with the keyboard hook installed (k-hook), whereas they can launch non-hook Hotkeys (reg).

KeyHistory Main Window Command

Whether you select “Key history and script info” from the menu or insert the KeyHistory command into a script, a view pops open displaying the script keyboard action.

Main Window Key History
Check out keyboard and mouse activity with the Main Window KeyHistory view. Helps to identify Virtual Keys (VK) and Scan Codes (SC) for use in Hotkeys.

I found this Main Window View particularly valuable when looking for Virtual Key and Scan Code values for the MousePrecise.ahk script. If you wonder what AutoHotkey actually does with each press of a key or click of a mouse, then start with KeyHistory.

You’ll note the other standard System Tray icon menu items (Reload Script, Edit Script, Window Spy, Pause Script, Suspend Hotkeys, and Exit (Terminate Script)) in the File menu of the Main Window.

You’ll find it easy to forget that the Main Window even exists, but if you encounter trouble with a particular script, right-click on the System Tray icon and select Open for a little insight.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s