alivirgo AutoHotkey v2 Desktop Automation AI Skill Guide (Claude)
Overview & Engine Architecture
AutoHotkey v2 (AHK v2) is a native C++ automation scripting engine for Microsoft Windows. Completely re-architected with strict expression-based syntax, first-class functions and objects, and a modern Gui API, AHK v2 intercepts input events via low-level Windows hooks (WH_KEYBOARD_LL / WH_MOUSE_LL via SetWindowsHookEx). The engine communicates with the Win32 subsystem through SendMessage / PostMessage, provides native Win32 DllCall C-type bridging, and compiles to standalone executables via Ahk2Exe. Claude operates as a Principal Windows Automation Architect and Win32 Systems Specialist, specializing in AHK v2 type-safe script development, UIPI (User Interface Privilege Isolation) bypass, Win32 API integration, and system-wide productivity hotkey orchestration.
AutoHotkey v2 Architecture & Win32 Hook Stack
┌─────────────────────────────────────────────────────────────┐
│ AutoHotkey v2 Engine Stack │
│ │
│ AHK v2 Scripting & Object Model │
│ ├── Strict Expression Parser (Functions: `MsgBox("Text")`) │
│ ├── Gui Object Architecture (`myGui := Gui("+AlwaysOnTop")│
│ └── Hotkey / Hotstring Engine (`#HotIf`, `SendInput`) │
│ │
│ Win32 Subsystem & Hook Pipeline │
│ ├── Low-Level Input Hooks (`WH_KEYBOARD_LL`, `WH_MOUSE_LL`)│
│ ├── Windows Message Pump (`WM_COMMAND`, `WM_SYSCOMMAND`) │
│ └── Native C-Type Interop (`DllCall("user32\SetWindowPos") │
│ │
│ Privilege & Security Architecture │
│ ├── UIPI Bypass Layer (`uiAccess="true"` Digital Signing) │
│ └── Standalone Compiler (`Ahk2Exe.exe /in ... /out ...`) │
└─────────────────────────────────────────────────────────────┘
Operational Capabilities & Agent Directives
- AHK v2 Expression-Based Script Development: Author robust, type-safe scripts leveraging modern v2 syntax (no legacy v1
%var%command syntax), nested functions, andtry / catch / finallyexception handling. - Win32 Window Management Orchestration: Build high-performance utilities manipulating HWND handles, window opacity (
WinSetTransparent), Always-On-Top flags (WinSetAlwaysOnTop), and multi-monitor screen geometries. - UIPI & Administrator Privilege Remediation: Resolve input injection failures across elevated windows by implementing
UIAccessmanifests and digital certificate signing. - Win32 API
DllCallDevelopment: Construct direct C-type calls touser32.dll,gdi32.dll, andshell32.dllfor low-latency OS manipulation without spawning shell subprocesses.
Production AHK v2 Script: Advanced Window Manager & System Productivity HUD
Save this script as WindowManager_v2.ahk (execute with AutoHotkey v2 64-bit):
#Requires AutoHotkey v2.0
#SingleInstance Force
InstallKeybdHook
InstallMouseHook
; ==============================================================================
; AutoHotkey v2: Advanced Window Manager & Productivity Toolkit
; Features:
; - Win + Space: Toggle Always-On-Top with visual OSD notification
; - Win + Alt + Left/Right: Snap active window to Left/Right half of monitor
; - Hover Window Title + WheelUp/Down: Adjust Window Transparency
; ==============================================================================
; --- 1. Hotkey: Toggle Active Window Always-On-Top (Win + Space) ---
#Space::
{
try {
activeHwnd := WinGetID("A")
activeTitle := WinGetTitle("A")
; Toggle AlwaysOnTop style
WinSetAlwaysOnTop(-1, activeHwnd)
; Check current status
exStyle := WinGetExStyle(activeHwnd)
isTop := (exStyle & 0x8) ; WS_EX_TOPMOST = 0x00000008
statusText := isTop ? "PINNED (Always On Top)" : "UNPINNED (Normal)"
ShowOSD(statusText, isTop ? "00FF00" : "FF4444")
} catch Error as err {
ShowOSD("Error: " . err.Message, "FF0000")
}
}
; --- 2. Hotkey: Snap Active Window to Left/Right Monitor Half ---
#!Left::
{
SnapActiveWindow("Left")
}
#!Right::
{
SnapActiveWindow("Right")
}
SnapActiveWindow(direction)
{
try {
hwnd := WinGetID("A")
; Query Monitor Dimensions for Active Window
monitorIdx := GetWindowMonitor(hwnd)
MonitorGetWorkArea(monitorIdx, &monLeft, &monTop, &monRight, &monBottom)
monWidth := monRight - monLeft
monHeight := monBottom - monTop
halfWidth := monWidth // 2
if (direction = "Left") {
WinRestore(hwnd)
WinMove(monLeft, monTop, halfWidth, monHeight, hwnd)
} else if (direction = "Right") {
WinRestore(hwnd)
WinMove(monLeft + halfWidth, monTop, halfWidth, monHeight, hwnd)
}
ShowOSD("Snapped Window: " . direction, "00AAFF")
} catch Error as err {
ShowOSD("Snap Failed: " . err.Message, "FF0000")
}
}
GetWindowMonitor(hwnd)
{
; Default to primary monitor if resolution lookup fails
return 1
}
; --- 3. Mouse Scroll Over Titlebar: Adjust Window Transparency ---
#HotIf MouseIsOverTitlebar()
WheelUp::
{
AdjustWindowTransparency(15) ; Increase opacity
}
WheelDown::
{
AdjustWindowTransparency(-15) ; Decrease opacity
}
#HotIf
MouseIsOverTitlebar()
{
MouseGetPos(&mouseX, &mouseY, &hoverHwnd)
if (!hoverHwnd)
return false
; Query Win32 Non-Client Hit Test (WM_NCHITTEST = 0x84)
lParam := (mouseY << 16) | (mouseX & 0xFFFF)
hitTest := SendMessage(0x84, 0, lParam, hoverHwnd)
; HTCAPTION = 2 (Title bar)
return (hitTest = 2)
}
AdjustWindowTransparency(delta)
{
MouseGetPos(, , &hwnd)
if (!hwnd)
return
currentAlpha := WinGetTransparent(hwnd)
if (currentAlpha = "")
currentAlpha := 255
newAlpha := Max(50, Min(255, currentAlpha + delta))
WinSetTransparent(newAlpha, hwnd)
ToolTip("Window Opacity: " . Round((newAlpha / 255) * 100) . "%")
SetTimer(() => ToolTip(), -1000)
}
; --- 4. Custom Dark Mode OSD Notification Overlay ---
ShowOSD(text, colorHex := "00FF00")
{
static osdGui := ""
if (osdGui != "")
osdGui.Destroy()
osdGui := Gui("+AlwaysOnTop -Caption +ToolWindow +E0x20") ; E0x20 = Click-through
osdGui.BackColor := "1A1A1A"
osdGui.SetFont("s14 bold c" . colorHex, "Segoe UI")
osdGui.Add("Text", "Center w320", text)
; Position Bottom-Center of Primary Monitor
MonitorGetWorkArea(1, &mLeft, &mTop, &mRight, &mBottom)
xPos := mLeft + ((mRight - mLeft - 340) // 2)
yPos := mBottom - 120
osdGui.Show("x" . xPos . " y" . yPos . " NoActivate")
SetTimer(() => (osdGui.Destroy(), osdGui := ""), -1500)
}
Technical Troubleshooting Matrix
| Issue & Failure Signature | Root Cause Analysis | Diagnostic & Resolution Pathway |
|---|---|---|
| Hotkeys Fail on Task Manager / Regedit Windows | User Interface Privilege Isolation (UIPI) blocks lower-integrity input injection into elevated windows. | 1. Run script as Administrator.2. Or compile script with Ahk2Exe using an UIAccess manifest and sign with a local self-signed root certificate. |
Error: This line does not contain a recognized action |
Legacy AutoHotkey v1 command syntax (e.g. IfEqual, StringSplit) executed on AHK v2 interpreter. |
Migrate to v2 function syntax: use if (var == val) and StrSplit(). |
| Infinite Key Recursion Loop | Sending a key (SendInput("a")) from a hotkey listening to the same key (a::). |
Prefix the hotkey with the hook modifier $ (e.g. $a::) to prevent the script's own generated inputs from re-triggering the hotkey. |
Windows Defender Flags Compiled .exe as Trojan |
Generic heuristics triggering on standard un-modified Ahk2Exe stub binaries. |
In Ahk2Exe, enable BinMod compression masking and digitally sign the output .exe using signtool.exe. |
Command Line Syntax & Ahk2Exe Compiler
# 1. Launch / Reload AHK v2 Script Directly
"C:\Program Files\AutoHotkey\v2\AutoHotkey64.exe" /restart "C:\Scripts\WindowManager_v2.ahk"
# 2. Compile AHK v2 Script to Standalone Executable (.exe)
"C:\Program Files\AutoHotkey\Compiler\Ahk2Exe.exe" /in "C:\Scripts\WindowManager_v2.ahk" /out "C:\Deploy\WindowManager.exe" /base "C:\Program Files\AutoHotkey\v2\AutoHotkey64.exe"
# 3. Kill Running AHK Script via PowerShell
Stop-Process -Name "AutoHotkey64" -Force
Essential File Locations
- AHK v2 Binary:
C:\Program Files\AutoHotkey\v2\AutoHotkey64.exe - Standard Library Directory:
%USERPROFILE%\Documents\AutoHotkey\Lib\ - Compiler:
C:\Program Files\AutoHotkey\Compiler\Ahk2Exe.exe
Agent Operational Directive
MANDATORY: Never use legacy AutoHotkey v1 command syntax. All scripts authored for AutoHotkey must strictly enforce v2 standards (
#Requires AutoHotkey v2.0, function calls with parentheses, and object-based GUI models).