AHK-RS: Cross-Platform AutoHotkey in Rust

中文文档 | English

A modern, cross-platform implementation of AutoHotkey written in Rust, supporting Windows, Linux, and macOS.

📚 Documentation

• 中文使用手册 - Complete Chinese documentation
• 用户指南 - Detailed user guide in Chinese
• 快速参考 - Quick reference in Chinese
• 常见问题 - FAQ in Chinese

🎯 Goals

• Cross-Platform: Single codebase that compiles natively on Windows, Linux, and macOS
• Performance: Fast execution with minimal memory footprint
• Compatibility: High compatibility with existing AutoHotkey v1 scripts
• Safety: Memory-safe implementation with minimal unsafe code
• Embeddable: Can be embedded as a library in other Rust applications

🚀 Features

Core Features (Phase 1-3)

• ✅ Hotkeys and hotstrings
• ✅ Basic commands (Send, Run, MsgBox)
• ✅ Control flow (If/Else, Loop)
• ✅ Cross-platform window management
• ✅ Virtual machine with stack-based execution

Platform Support

Platform	Hotkeys	Hotstrings	Send	WinActivate	Status
Windows	✔	✔	✔	✔	✅ Full
Linux	✔	✔	✔	◐	🚧 X11
macOS	✔	✔	✔	◐	🚧 Limited

◐ = Partial support (requires specific permissions/setup)

📦 Installation

From Source

git clone https://github.com/your-org/ahk-rs
cd ahk-rs
cargo build --release

Pre-built Binaries

Download from Releases

🔧 Usage

Command Line

# Run an AHK script
ahk-rs script.ahk

# Interactive mode
ahk-rs --interactive

Embedded in Rust

use ahk_rt::{Engine, Error};

fn main() -> Result<(), Error> {
    let mut engine = Engine::new();
    engine.load_file("demo.ahk")?;
    engine.run()
}

Example Script

; demo.ahk - Compatible with original AutoHotkey syntax
^j::
Send, Hello from Rust-AHK
return

::btw::by the way

🏗️ Architecture

ahk-rs/
├── crates/
│   ├── ahk_core/      # Platform-agnostic lexer, parser, VM
│   ├── ahk_platform/  # Platform abstraction layer
│   ├── ahk_builtin/   # Built-in command implementations
│   ├── ahk_rt/        # Embeddable runtime API
│   └── ahk_cli/       # Command-line interface
├── scripts/           # Test scripts and examples
└── tests/             # Integration tests

🛠️ Development

Prerequisites

• Rust 1.78+ (MSRV)
• Platform-specific dependencies:
  • Linux: X11 development libraries
  • macOS: Xcode command line tools
  • Windows: Windows SDK

Building

# Build all crates
cargo build

# Run tests
cargo test

# Run with debug logging
RUST_LOG=debug cargo run -- script.ahk

Platform-Specific Setup

Linux

# Ubuntu/Debian
sudo apt install libx11-dev libxtst-dev

# Fedora
sudo dnf install libX11-devel libXtst-devel

macOS

Enable "Accessibility" permissions for the terminal/IDE you're using.

📋 Roadmap

• Phase 0: Project setup and design
• Phase 1: Lexer and parser implementation
• Phase 2: Virtual machine and runtime
• Phase 3: Platform abstraction layer
• Phase 4: Built-in commands migration
• Phase 5: Cross-platform packaging and CI
• Phase 6: Plugin system and backward compatibility

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

📄 License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT License (LICENSE-MIT)

at your option.

🙏 Acknowledgments

• Original AutoHotkey project
• Rust community for excellent cross-platform libraries