AutoHotKey Agents.md Template

AGENTS.md

Role

You are an expert AutoHotkey v2 code generator. Under no circumstances should you produce v1-style code or syntax.

Guide for Coding Agents

This document defines how the coding agent works in this repository and the expectations for logging, execution, and implementation. It is tailored to the current layout of this repo and the feature set described in requiremetns.txt.

Scope & Objectives

• Implement and evolve AutoHotkey v2 script per requiremetns.txt.
• Keep the codebase aligned with AutoHotkey v2 syntax and the repository’s style guidelines.
• Use the designated log files at all times for debugging and error inspection.

AutoHotkey v2 Rules & Conventions

Always keep these rules in context when coding:

1. Always include #Requires AutoHotkey v2.0+ at the top of every script.
2. Use only expression-based syntax—no legacy command forms. For example, use MsgBox("Hi"), never MsgBox, Hi.
3. Use := for all assignments. Do not use = as assignment.
4. For comparisons, use = for case-insensitive or == for case-sensitive. Never use deprecated operators like <>.
5. Never use percent signs for variable dereferencing (like %var%), nor command-style comma-separated parameters.
6. The auto-execute section is for initialization only (e.g., constants, hotkey and timer setup).
7. All logic must sit inside functions. It’s okay to call functions defined later in the script.
8. Inside functions, variables are local by default. To access globals, declare them explicitly with global VarName at the top of the function.
9. Use static var := value inside functions to persist data across calls.
10. Always use native double-colon hotkey syntax (e.g., ^!j::). Only use Hotkey() if truly required for dynamic assignment.
11. Use the v2 hotstring functionality (Hotstring() or #Hotstring), not legacy option syntax.
12. For GUIs, use the Gui() object API. Set options before adding controls or showing the window.
13. Use try / catch / throw for error handling. Include #Warn during development to catch issues early.
14. Use literal objects ({key: value}) and arrays ([item1, item2]) with dot-notation (obj.prop or arr[1]).
15. Use SetTimer() with a function reference, never labels.
16. Build strings with . concatenation or continuation sections. Do not use legacy behavior like comma-based concatenation.
17. Stick to a consistent naming convention (e.g., camelCase or snake_case for variables/functions, PascalCase for classes).
18. Fail if any rule is broken—do not silently assume.
19. Avoid these common pitfalls: a. Using = instead of := (AI often confuses these). b. Missing braces around multi-line hotkeys or functions. c. Using deprecated syntax like %var%, comma-separated parameters, or v1-style Send. d. Scope errors: accessing globals without declaring them. e. Converting quirky v1 constructs like if !var, stacked labels, or label-based logic—explicitly refactor them to functions and use IsSet(var) instead of if !var. f. Invalid variable names (e.g., names starting with a digit)—prefix with _ if needed. NEVET name variables with reserved AutoHotKey keywords. g. GUI control naming conflicts or overlapping—ensure unique identifiers. h. Misusing API calls like DllCall, RegExMatch, RegExReplace due to argument order—consult v2 docs carefully. i. Ambiguous semicolons inside strings—ensure correct parsing.
20. Always test logic by reasoning through the strict v2 interpreter behavior: uninitialized variables, forward declarations, scope.
21. When coding always ask yourself if you are following best practices of v2 and not using v1 code by mistake.

Planning

You will always create running PLAN.md file and validate it after each step to make sure all steps are done. Keep updating this file. You can re-create this file when moving to different functionality based on requiremetns.txt.

Run, Test

• Run the script with /ErrorStdOut to capture any startup errors to the console if possible.
• Run script (Windows): "C:\\Program Files\\AutoHotkey\\v2\\AutoHotkey64.exe" {SCRIPT_PATH_HERE}
• Run a specific module (if modularized): adjust the path accordingly.
• Run tests (if test/runner.ahk exists): "C:\\Program Files\\AutoHotkey\\v2\\AutoHotkey64.exe" test\\runner.ahk
• While debugging, start and stop the script automatically so you can check back logs eg error.log or debug.log.
• Make sure you are also able to capture startup errors, the ones which can get triggered even before error.log or debug.log are created.
• You have powershell powertool available to use any time.

Note: Some of the above paths correspond to a future structured layout; adapt them to the current single‑file script as needed.

Mandatory Logging Policy

You MUST use error.log and debug.log in the repo root at all times.

• Always read logs after running the app or tests:
  • PowerShell: Get-Content -Tail 200 -Path error.log
  • PowerShell: Get-Content -Tail 200 -Path debug.log
  • Cygwin: tail -n 200 error.log and tail -n 200 debug.log
• When a command fails or an error is suspected, append a concise, timestamped entry to error.log describing:
  • The command or action
  • The error message/exit code
  • The relevant file/function if known
• For investigative output or trace messages during development, append to debug.log with timestamps.
• In final user messages, summarize noteworthy log findings (not full dumps unless requested).
• Never store secrets or PII in logs; avoid logging sensitive file contents.
• error.log and debug.log files must be deleted every time app is started. Code this in script itself.
• When having trouble debugging, add more logs to script so you can analyze each step.

Script‑side logging expectations

When modifying/adding AHK code:

• Wrap high‑risk operations (file I/O, JSON parse, GUI updates, timers) with try/catch and write exceptions to error.log using FileAppend.
• Add targeted FileAppend calls for key lifecycle events to debug.log (app start, window show/hide, config load/save, reminder triggers).
• Prefer a small logging helper (e.g., LogDebug(msg) / LogError(msg)) to centralize timestamps and file paths.
• Delete error and log at startup

Example (AHK v2):

; ---------- Logging ----------
global LOG_ERRORS := A_ScriptDir "\\error.log"
global LOG_DEBUG  := A_ScriptDir "\\debug.log"

try FileDelete(LOG_ERRORS)
try FileDelete(LOG_DEBUG)

LogDebug(msg) {
  FileAppend(Format("[{1}] DEBUG: {2}\r\n", A_Now, msg), LOG_DEBUG)
}

LogError(msg) {
  FileAppend(Format("[{1}] ERROR: {2}\r\n", A_Now, msg), LOG_ERRORS)
}

OnError(LogUnhandled)

LogUnhandled(e, mode) {
  LogError(Format("Unhandled: {1} at {2}:{3}", e.Message, e.File, e.Line))
  return false
}

Error Handling & Safety

• Avoid writing to protected folders; prefer %A_AppData% or %A_Temp% for transient files.
• Do not require admin privileges/UAC unless strictly necessary.
• Handle file I/O defensively and validate JSON/INI contents.

Agent Workflow Expectations

• Explore repo → implement focused changes → run script/tests → stop scripts → inspect error.log and debug.log → report back.
• Use small, reviewable patches that address the root cause when fixing bugs.
• Keep changes minimal and consistent with the existing style.

Very Important

• Only use v2 of AutoHotKey and do not use any v1 code which is not supported in v2.

This prompt gives coding agent power to not only develop script but also run it, debug it and fix errors automatically! Works especially well with OpenAI's Codex.

This project was vibe-coded with above: https://github.com/sarfraznawaz2005/TodoManager