AutoHotkey v2 · Claude Code plugin · MIT

An AutoHotkey v2 plugin for Claude Code that checks every edit.

ClautoHotkey runs the real interpreter on each .ahk file Claude writes and sends any error straight back to it. It loads the rules a file needs the first time that file is edited, and it can grade scripts without letting them touch your desktop. This page explains how each part works and why it's built this way.

12hooks
19skills
9agents
11rules
23modules
4grading tiers

What it is

Language models make the same mistakes in AutoHotkey v2 again and again. They mix in v1 syntax, use JavaScript habits such as object literals as dictionaries or new ClassName(), forget that arrays start at 1, and use alpha-only features on builds that don't have them. Most of these errors only show up when the script runs, and a broken AutoHotkey script can send keystrokes, move windows or delete files.

ClautoHotkey runs the interpreter after every edit, so these errors are caught as soon as they're written. It has four parts:

Tooling

The harness

Hooks, rules, skills and agents for Claude Code. It checks each edit and sends AHK tasks to the right skill or agent. It installs as a plugin.

Engine

The +Console fork

A console-enabled AutoHotkey v2 build with real stdout, Print, Eval, JSON diagnostics and structured exit codes. Stock v2 works too.

Knowledge

Modules

Markdown modules on classes, GUI, errors, text, DllCall, COM, WinAPI, versions and more. A corpus lint keeps out v1 and removed alpha syntax.

Docs

ahk-mcp (optional)

An MCP server for documentation search, completion and diagnostics. Nothing else depends on it.

The edit loop

Claude Code runs hooks before and after each tool call. ClautoHotkey puts its checks in those hooks, so the model can't skip them. This is what happens around one edit:

Session starts

ahk-session-primer loads the AHK context and a routing table: which skill or agent fits which task.

First edit of a file

inject-rules loads the rule matching the file (v2 syntax, GUI work, Lib/), once per session.

Edit is written

The model writes the .ahk file with an Edit or Write call, as it would in any project.

Interpreter checks it

ahk-post-edit runs a syntax check, then briefly runs a standalone script to catch runtime errors.

Broken: the error goes back to Claude

The hook returns the interpreter's error as a blocking message, so Claude fixes the file before writing more code. The failure is logged to error-log.jsonl.

Clean: Claude carries on

If the script is already running, it is restarted so it runs the new code.

On the fork the check is check /Diag=json; on stock AutoHotkey it falls back to /validate.

Other hooks cover the rest. check-ahk-binary blocks any Bash call that would run a different AutoHotkey build than the configured one. detect-v1-syntax warns when a prompt contains v1 code. post-compact-state lists the scripts still running after the conversation is compacted and lets the rules load again. check-git-account is an opt-in guard against pushing as the wrong identity.

If the interpreter can't be found, the hook says so instead of reporting a pass.

Three layers of help

Apart from the hooks, the harness gives Claude three kinds of help:

LayerWhen it loadsWhat it's for
RulesThe first time you edit a matching fileShort, binding notes: v2 syntax, staying on the build you have, GUI layout, library conventions. Most load themselves; the rest are reference notes the session primer points to.
SkillsWhen invoked as /ahk-gui, /ahk-fix and so onThe default entry point. Some load a knowledge module; the others drive the tooling: run, REPL, convert v1, scaffold a class, audit error handling.
AgentsIn their own context windowBounded investigations: dependency graphs, profiling, UI Automation trees, COM introspection, test generation.

Each one takes up a different amount of context, which is what the next section is about.

Why it's built this way

Most of the design follows from one limit: the model has a fixed amount of context. Anything a script can check is checked by a script, and everything else stays out of context until a task needs it.

Principle 1

Checks belong in hooks, not in instructions

A model can read "always validate your script" and still not do it, but it can't skip a hook. So everything that must happen every time is a hook: checking each edit, blocking the wrong interpreter, restarting a running script. Hooks also use no context, because they run outside the prompt.

Principle 2

Every component costs context

Text that's always loaded takes up context in every session. A skill takes none until it's used. The harness ranks the options by cost, and new guidance goes in the cheapest one that works:

ComponentIn contextCost
HookInside the tool loopCan't be skipped; no context cost
Script in Tools/On demandNone
SkillWhen invokedNothing until used
AgentIts own context windowA start-up cost per launch
Narrow ruleFirst edit of a matching filePaid when it fires
CLAUDE.md, rules on every .ahkEvery session, every editPaid on every run

lint_harness.py measures the always-loaded text (about 25,600 characters now) and warns when it goes over its cap, so adding to it means cutting something else.

Principle 3

Load knowledge only when a file or task needs it

A GUI rule doesn't help while you're editing a regex helper. Each rule says when it loads: a path pattern, a string the file contains (a file that calls Gui( gets the GUI rule whatever it's called), or build: fork to skip stock AutoHotkey. Each one loads once per session. Each skill's description lists the tasks it covers, so Claude can match a task to a skill on its own.

Principle 4

Write for the build the user actually has

The modules are tested on the v2.1-alpha +Console fork and use its features, but most users run stock v2.0. The ahk-target rule limits generated code to what the user's build supports, and the modules give a stock v2.0 alternative for each feature it lacks. The harness works on both; the fork adds better diagnostics.

Principle 5

No silent passes

A check that quietly does nothing is worse than no check, because people trust it. So a missing interpreter is reported, a timeout is a failed result rather than a skip, a tier that didn't run is recorded as "skipped" rather than a zero, and the live tier reports error until its backend is installed. A hook that reads a field Claude Code never sends would look fine in review and do nothing, so a smoke test sends every hook a real payload and checks its response.

Principle 6

Change it only when there's evidence

A mistake that happens once isn't a reason to add a rule. The harness changes only when a recorded mistake, a pattern in the error log or a failed run supports it, and leaving it unchanged is an acceptable outcome. How it learns from mistakes covers the process.

Grading scripts safely

Checking that a script parses is safe. Checking that it works means running it, and a running AutoHotkey script can type, click and write files. The grading harness runs a script through four tiers in order, each riskier than the last, and stops at the first one it fails.

staticTier 1

The fork's check and /validate, then a structural lint (empty catches, v1-isms) and scope-aware analysis (a symbol table, a call graph, undefined calls, properties called as methods), both built on a tree-sitter grammar.

pureTier 2

Finds the script's unit tests (Name.test.ahk, Test_Name.ahk, beside it or under Tests\) and runs them with the TestKit assertion library. The results are deterministic and no model is involved.

dry-runTier 3

Runs the real script in place with a shim injected. Input, window control, messages, Gui, dialogs, hotkeys, Run, Shutdown and file, registry and download writes are recorded instead of performed. The script runs in a job with a memory cap that is killed when the run ends, and a window watcher and a clipboard guard catch anything the shim misses.

liveTier 4

The only tier that touches a desktop, and it uses a hidden one. Live runs share focus and synthetic input, so they run one at a time under a lock, never in parallel.

One result format

Every tier writes the same NDJSON object through one shared module, HarnessCore.ahk. Every field is always present, so a reader never has to tell a missing field from an empty one, and an end marker shows the line wasn't cut off. CheckResults.py drops empty, timed-out and contradictory results, and Report.py turns the rest into SARIF, JUnit, GitHub annotations or Markdown.

{ "tier": "static", "status": "pass", "parse": "clean",
  "findings": [ { "rule": "empty-catch", "line": 88, "severity": "high" } ],
  "sentinel": "AHKHARNESS-END" }

SelfTest.ahk --run checks that the gates still protect the machine: it runs test scripts with known results and confirms none of their side effects happened. Reduce.ahk cuts a failing script down to the fewest lines that still fail the same way.

How it learns from mistakes

Every failed interpreter run and blocked edit goes into an error log. /ahk-mistakes reads it for recurring patterns, and Tools/lessons.py propose turns those rows into candidate lessons. A lesson needs all four of these fields:

FieldExample, from a real lesson
CueA fat-arrow callback whose body is a call that returns nothing, like (*) => this.Toggle(), on the +Console fork
LessonThe change it argues for, on a named component (here, rules/ahk-v2-syntax.md)
EvidenceThe log rows and runs that showed it
ConfidenceHigh, medium or low

An entry missing any field is refused. A recurring error whose cause hasn't been verified stays a proposal and doesn't become a lesson. The approach is adapted from Google Research's Harness² (the design only, not its code). The lesson library and the lint below are built. The full loop, which uses model time, is described in Tools/harness/ADAPT.md, but no script runs it yet. In that loop a change is proposed, tested in a separate worktree, compared blind against the current harness, and dropped if it doesn't do better.

lint_harness.py checks the harness itself. It confirms that every skill is wired up and listed, every script a hook names exists, every rule has a trigger, the counts in the README and CLAUDE.md match the files, and the always-loaded text is under its cap.

The console engine

Stock AutoHotkey is a GUI program, so its errors appear in message boxes that a model can't read. The +Console fork adds output that a program can read:

  • Real stdout and stderr, plus Print(fmt, values*), so a script's output reaches the model directly.
  • Eval(expr) and a repl subcommand, which /ahk-eval drives for quick checks without writing a file.
  • JSON diagnostics from check /Diag=json, which the post-edit hook parses into exact line and message.
  • Structured exit codes and crash logs: 12 for a parse failure, 10 for an uncaught error, 130 for Ctrl+C.

Stock AutoHotkey v2 still works. The hooks fall back to /validate, and you lose Print, Eval and JSON diagnostics. The grading gates do need the fork.

Install

As a Claude Code plugin

/plugin marketplace add TrueCrimeDev/ClautoHotkey
/plugin install clautohotkey@clautohotkey

The skills, rules and edit checks then apply in any project, and the harness finds your AutoHotkey install the first time it runs. To pin an interpreter or switch on the fork's diagnostics, put a harness.env in your project root:

# every key is optional
AHK_BIN_WIN="${WIN_HOME}\Documents\AutoHotkey\bin\AutoHotkey64.exe"
AHK_DIAG_JSON=1   # only on the +Console fork

As a clone, or in OpenCode

git clone https://github.com/TrueCrimeDev/ClautoHotkey.git
cd ClautoHotkey && ./setup.sh          # Claude Code, files in your tree
./opencode/install.sh                  # OpenCode 1.x, same hooks and skills
./Tools/verify.sh                      # proves the hooks really block a broken edit

Needs Git Bash or WSL, AutoHotkey v2, and jq or Python 3.8+. The full walkthrough is in GETTING-STARTED.md, and the README lists every skill, agent and hook.

AutoHotkey v2 only. There is no v1 support, because part of the harness's job is keeping v1 syntax out.