Appearance
AHK
The AutoHotkey v2 stack pack. AutoHotkey v1 and v2 share a file extension and look alike, so v1 syntax is one of the most common stale-memory traps a model falls into – and finn writes v2 only. The pack guards both ends of a script's life: a post-edit gate rejects the high-signal v1 patterns before they land, a headless dry-run validates a script without running it, and a pre-run gate stops a kill that would take out every script on the box instead of the one the agent meant. The syntax gate and the dry-run work on .ahk edits and on demand; the kill guard fires on every Bash or PowerShell command and only acts on the ones that name autohotkey.
In Practice
The guard bounces a v1-ism. The agent, reaching for a remembered v1 pattern, writes MsgBox %count% into reload.ahk. The moment the edit lands, the PostToolUse guard scans the saved file, catches the percent-deref, and blocks the edit with exit 2, printing the v2 form to stderr so Claude Code feeds it straight back:
ahkv2-guard, reload.ahk has autohotkey v1-isms, finn is v2-only, fix these:
line 3, v1 percent-deref %var%, v2 uses the bare name in expressions, msgbox var not msgbox %var%
see .claude/memory/lessons/ahk.md for the v1 to v2 notes if the memory part is installedThe agent reads the correction and rewrites the line as MsgBox(count) – the bare name in an expression, function-call syntax – and the re-edit passes clean.
Smoke-test a script headless. You have a script written and want to know it loads before wiring it to a key, so you validate it without running it:
nu .claude/stack/ahk/ahk-dryrun.nu run reload.ahkAutoHotkey v2 loads the script with /validate – which reports load-time errors then exits without running, so a persistent hotkey script never hangs the harness – and /ErrorStdOut routes any error to text instead of a message box. A clean script reports nothing but the ok line:
ok, reload.ahk validated with no load errorsA script with a syntax or load error prints reload.ahk reported: followed by the error text AutoHotkey handed back on stderr. And if AutoHotkey v2 is not on PATH or in the usual install spots, the dry-run degrades clean rather than failing:
AutoHotkey not found on PATH or the usual install spots, install autohotkey v2The kill guard bounces a name sweep. finn has more than one script running at once, and the agent wanting one gone reaches for taskkill /IM AutoHotkey64.exe, which kills by image name rather than by process. The PreToolUse guard catches it before the command ever runs, blocks with exit 2, and prints the reason plus whatever ahk-ps.nu --plain reports is currently running so the agent has a pid to aim at:
ahk-kill-guard, blocked, this kills EVERY running autohotkey script and not just yours:
taskkill /IM picks by image name, so it takes every autohotkey process at once
kill the one you started by pid instead, taskkill /PID <pid> or Stop-Process -Id <pid>
running right now:
<the ahk-ps.nu --plain listing, one line per pid>The agent rereads a pid off the listing and reissues the kill as taskkill /PID <pid>, which passes clean, the pid forms are always allowed.
Check what's running before reaching for a kill at all. Run the lister on its own:
nu .claude/stack/ahk/ahk-ps.nu --plainwhich prints pid, script, and start time per row, a shared root: line once above them, or no autohotkey scripts running when nothing is up.
An example outcome. A v1-ism never reaches disk, a load error in a script the agent just wrote surfaces as plain text before that script is ever bound to a hotkey, and a blind name-based kill never reaches the process table – the agent gets a pid list to aim at instead of finn's whole keyboard setup going quiet.
Key Files
ahkv2-guard.nu
The gate – a PostToolUse hook on .ahk files (matcher Edit|Write|MultiEdit). It reads the saved file line by line and runs four string-and-regex checks for the high-signal v1 tells, no parsing. On the first batch of hits – capped at ten – it exits 2 and prints each one with its line number and the v2 form it wants, so Claude Code feeds the correction back; a clean or unreadable file exits 0, and any internal error fails open. It skips comment lines, and the checks are tuned to accept the same false positives style-lint tolerates: the = check only fires on the statement form var = value, the label check excludes v2 case/default and :: hotkeys, and the command check ignores lines with :=.
ahk-kill-guard.nu
The pre-run gate – a PreToolUse hook on Bash|PowerShell (matcher Bash|PowerShell). It only looks at a command whose lower-cased text contains "autohotkey" – anything else exits 0 untouched, the gate has no opinion on the rest of your shell. A naming command is checked against six sweep patterns: taskkill with /IM, Stop-Process -Name, a Get-Process sweep piped into Stop-Process or kill, pkill/killall, a wmic filter ending in delete or terminate, and a nushell ps | where | kill pipeline. A hit exits 2, prints the reason, and shells out to ahk-ps.nu --plain to paste the live listing into the block message so the agent has something to act on. The pid forms – taskkill /PID <n>, Stop-Process -Id <n>, a bare kill <n> – are never touched, that's the whole point of the gate. String checks only, no shell parsing, same HARNESS_HOOKS_OFF recursion guard and fail-open trade ahkv2-guard.nu already takes.
ahk-ps.nu
The lister – shows the autohotkey processes running right now: pid, script, and start time, so a kill has a pid to target instead of a name to sweep. ahk-kill-guard.nu shells out to it for its block message, and it reads fine standalone too. Windows only – the script path comes off the process's command line, which only Win32_Process carries, nushell's own ps doesn't, so ahk-list returns an empty list rather than erroring anywhere else. It takes the last .ahk match in the command line rather than the first, because the v2 launcher puts its own launcher.ahk in front of the real script; a compiled script has no .ahk in its command line at all, so it falls back to showing the raw command. The folder every row shares gets pulled off the front and printed once as a root: line, leaving only the part that differs per row. --plain drops the table for flat text, which is what lands in the kill guard's block message.
settings-fragment.json
The wiring – two entries merged into a project's .claude/settings.json: a PreToolUse block matching Bash|PowerShell that calls ahk-kill-guard.nu, and a PostToolUse block matching Edit|Write|MultiEdit that calls ahkv2-guard.nu. harness install --parts ahk merges the fragment for you unless you pass --no-wire; if it didn't land, harness hooks and press w. Until then both hooks sit on disk looking installed and doing nothing.
README.md
The pull rule – the module's own doc, covering all three tools and carrying the line you paste into a target CLAUDE.md: before writing AutoHotkey read .claude/memory/lessons/ahk.md, use := for assignment, function-call syntax like MsgBox(text), bare names in expressions not %var%, and functions or closures over subroutine labels.
What the Guard Catches
The four checks are the high-signal v1 tells, string and regex only. Each fires on a pattern and hands back the v2 form it wants:
| v1 pattern | What it is | The v2 form it wants |
|---|---|---|
MsgBox %var% | a percent-deref | the bare name in an expression – MsgBox var |
MsgBox, text | legacy command syntax, a comma arg list | a function call – MsgBox(text), Send(keys) |
x = 5 | a statement-level = assignment | := assignment – x := 5 |
Label: | a bare subroutine label | a function or closure – SetTimer(myFunc, 1000) |
The false positives are accepted the way a style-lint accepts them: a bare = is a valid comparison inside an expression, so the check only fires on the statement form, and the label check lets v2 flow keywords and :: hotkeys through.
What the Kill Guard Catches
Six sweep patterns, all string checks against the lower-cased command, all firing only once the command already names autohotkey:
| Sweep pattern | What it is | Why it's blocked |
|---|---|---|
taskkill ... /IM | image-name kill | taskkill /IM picks by image name, so it takes every autohotkey process at once |
Stop-Process -Name | the same thing in PowerShell | Stop-Process -Name picks by image name, so it takes every autohotkey process at once |
Get-Process piped to Stop-Process or kill | a name-matched sweep into a kill | a Get-Process sweep hands every matching pid to the kill, not just the one you started |
pkill / killall | name matchers | pkill and killall match on the name, so every autohotkey process goes with it |
wmic process where ... delete or terminate | a wmic name filter | a wmic name filter terminates every process it matches, not one of them |
ps | where ... | kill | a nushell name-matched pipeline | a ps | where name | kill pipeline selects by name, so every autohotkey process goes |
The pid forms are always allowed, since each one is aimed at a single process rather than a name: taskkill /PID <n>, Stop-Process -Id <n>, a bare kill <n>. A plain Get-Process AutoHotkey with no kill piped after it passes too, listing is fine, only a sweep that also kills is bounced.
Connects to
- Registers a PreToolUse gate and a PostToolUse gate that sit alongside the hooks pack's – Claude Code runs every matching hook, and both of these share the pack's
HARNESS_HOOKS_OFFrecursion guard and its fail-open default, no-opping when a harness hook spawned Claude somewhere up the chain. - Leans on memory – both the syntax guard's block message and the README's pull rule point at
.claude/memory/lessons/ahk.md, the ahk lessons slice, so the v1-to-v2 notes live there and the guard only has to reference them. - Placed by the installer –
harness install --parts ahkcopies the module to.claude/stack/ahk/, and itssettings-fragment.jsoncarries both thePreToolUseandPostToolUseentries, and the same install merges them unless--no-wiresays otherwise. - The end-user quick reference is the module's own
USAGE.md, atharness/modules/stack/ahk/USAGE.md– it's the source of truth for commands, config, and gotchas, this page is the fuller depth of the same three tools.