🧩 VS Code Extension 🔁 AHK v1 → v2 📂 Open Source
AHK Converter v0.2.0
Convert AutoHotkey v1 scripts to v2 with enhanced user experience inside VS Code
Features
Core Conversion Features
- Convert AHK v1 to v2 using the community converter and AutoHotkey v2
- Multiple output options: open in new tab, replace current file, or show enhanced diff
- Batch processing: convert multiple files at once with progress tracking
- Enhanced diff view: side-by-side comparison with color-coded changes
- Works offline once AutoHotkey v2 is installed
User Experience Enhancements
- Enhanced error messages with actionable recovery suggestions
- "Learn More" links to documentation for common errors
- Visual indicators with different message types (info, warning, error)
- Conversion statistics showing lines processed, warnings, errors, and timing
- Progress indicators for long-running operations
- Context menu integration for quick access
- Keyboard shortcuts for power users
Advanced Features
- Input validation with detailed warnings and error reporting
- Conversion validation to ensure output quality
- Configurable validation levels (strict, normal, lenient)
- Customizable diff view options
- Batch output directory management
- Auto-save options for converted files
Installation
- Install AutoHotkey v2 from autohotkey.com
- Install this VS Code extension:
- From VS Code Marketplace: Search for "AHK Converter"
- From VSIX: Download and install the .vsix file
- From source: Open this folder in VS Code and press F5 to launch the Extension Host
- Configure settings (optional) - see Settings section below
Usage
Single File Conversion
- Open a v1
.ahk file in VS Code
- Use one of the following methods:
Command Palette (Ctrl+Shift+P / Cmd+Shift+P):
AHK: Convert v1 to v2 - open in new tabAHK: Convert v1 to v2 - replace current fileAHK: Convert v1 to v2 - show enhanced diff
Context Menu (right-click on .ahk file):
- Convert v1 to v2 - open in new tab
- Convert v1 to v2 - replace current file
- Convert v1 to v2 - show enhanced diff
Keyboard Shortcuts:
Ctrl+Shift+A (Windows/Linux) or Cmd+Shift+A (Mac): Convert to new tabCtrl+Shift+D (Windows/Linux) or Cmd+Shift+D (Mac): Show diff
Batch Conversion
- From Command Palette: Run
AHK: Convert multiple files (batch)
- From Explorer: Select multiple .ahk files, right-click, choose batch conversion
- Select files in the file picker dialog
- Monitor progress with the progress indicator
- Review results and choose save options:
- Save All (including failed conversions with error logs)
- Save Successful Only
- Cancel (don't save)
Enhanced Diff View
The enhanced diff view provides:
- Side-by-side comparison of original vs converted code
- Color-coded changes for easy identification
- Line numbers for reference
- Context lines around changes
- Accept/Reject options for individual changes
- Action buttons for accepting all or selected changes
Error Handling
When errors occur, you'll see:
- User-friendly error messages explaining what went wrong
- Recovery suggestions with actionable steps
- "Learn More" links to relevant documentation
- "Show Details" option to view technical information in output channel
Settings
Core Settings
ahkConverter.autoHotkeyV2Path: Path to AutoHotkey v2 executable. If empty, uses AutoHotkey64.exe from PATH.ahkConverter.converterScriptPath: Path to v2converter.ahk. Defaults to the bundled file at ${extensionPath}/vendor/v2converter.ahk.ahkConverter.strictWindowsOnly: If true, warn on non-Windows platforms.
User Experience Settings
ahkConverter.enableEnhancedDiff: Enable enhanced diff view with better highlighting and options. (Default: true)ahkConverter.showConversionStats: Show detailed conversion statistics in status bar. (Default: true)ahkConverter.enableNotifications: Show enhanced notifications with actionable options. (Default: true)
Batch Processing Settings
ahkConverter.defaultOutputNaming: How to name converted files in batch mode.
suffix: Add '_v2' suffix to original filename (default)directory: Save to a separate 'v2' subdirectoryprompt: Prompt for filename each time
ahkConverter.batchOutputDirectory: Default output directory for batch conversions. If empty, prompts for directory.ahkConverter.autoSaveAfterConversion: Automatically save files after successful conversion. (Default: false)
Validation Settings
ahkConverter.validationLevel: Level of validation to perform on AHK files.
strict: Strict validation with detailed checksnormal: Normal validation with standard checks (default)lenient: Lenient validation with minimal checks
Diff View Settings
ahkConverter.diffViewOptions: Options for diff view display.
showLineNumbers: Show line numbers in diff view. (Default: true)highlightChanges: Highlight changes with color coding. (Default: true)ignoreWhitespace: Ignore whitespace changes in diff. (Default: false)contextLines: Number of context lines to show around changes. (Default: 3, range: 0-10)
Troubleshooting
Common Issues
"AutoHotkey v2 executable not found"
- Ensure AutoHotkey v2 is installed
- Set the correct path in
ahkConverter.autoHotkeyV2Path setting
- Try using the "Open Settings" action in the error notification
"Converter script not found"
- Verify the extension is properly installed
- Check
ahkConverter.converterScriptPath setting
- Reinstall the extension if the file is missing
"Validation failed"
- Check if the file contains AHK v1 syntax
- Ensure the file is not empty or corrupted
- Try with a simpler AHK file first
"Conversion failed"
- Check the output channel for detailed error information
- Verify AutoHotkey v2 is working correctly
- Try converting a simpler file first
Slow conversion on large files
- Consider using batch mode for multiple files
- Disable enhanced diff view if not needed
- Increase validation level to "lenient" for faster processing
Memory issues with batch processing
- Process files in smaller batches
- Close other applications to free memory
- Restart VS Code if needed
Getting Help
- Check the output channel: View → Output → "AHK Converter"
- Review error notifications: Click "Show Details" for technical information
- Visit documentation: Use "Learn More" links in error messages
- Report issues: GitHub Issues
Advanced Usage
Custom Validation
You can adjust the validation level based on your needs:
- Strict: Best for critical production code
- Normal: Good balance of safety and performance
- Lenient: Fastest, minimal checks
Batch Workflow
For large projects:
- Organize AHK files in logical groups
- Use batch conversion with directory output naming
- Review conversion statistics for quality assessment
- Test converted files before deployment
The extension works well with:
- AutoHotkey LSP for syntax highlighting and IntelliSense
- Git for version control of converted files
- Build tools for automated conversion workflows
Contributing
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
Changelog
See CHANGELOG.md for version history and updates.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgments
- AutoHotkey Community for the v2 converter script
- AutoHotkey Team for the v2 language and tools
- VS Code Team for the extension API and platform
Support
Enjoy converting your AHK scripts! 🚀
