Skip to content

Home

Jump to bottom
Washik edited this page Feb 22, 2026 · 13 revisions

Windows Event Automation Engine

Welcome to the WinEventEngine documentation! This wiki contains everything you need to understand, configure, and extend the engine.

What is WinEventEngine?

A universal event automation system for Windows that monitors system events (file changes, window activity, process creation, registry modifications) and executes automated actions based on configurable rules.

Automate everything:

  • Play/pause media when focusing specific windows
  • Auto commit changes to your config/dot files/folders
  • Auto build/test an application under configurable conditions
  • Get Webhook (Discord/Slack/Telegram/etc) notifications for configurable events
  • Send API requests for configurable conditions/events
  • Write easy-to-learn Lua scripts to customize everything
  • Watch it all happen in real-time on the web dashboard
  • Much more! Simple configuration, powerful results

Key Features

  • Event Monitoring: File system, windows, processes, and registry
  • Rule Engine: Pattern-based matching with Lua scripting
  • Web Dashboard: Real-time monitoring at http://localhost:9090
  • Windows Service: Run as background service
  • Plugin System: Write custom actions in Lua

First Time Setup (5 minutes)

New to WinEventEngine? This minimal example verifies everything works. You'll create a file watcher that logs when text files are created.

Requirements:

1. Download

Download engine.exe from GitHub Releases and save it to a folder (e.g., C:\Tools\win_event_engine\).

2. Create Your First Config

Create a file named config.toml in the same folder as engine.exe. This config watches the test_folder subdirectory for new .txt files and logs when they're created:

[engine]
event_buffer_size = 100
log_level = "info"

# Watch for new files in a test directory
[[sources]]
name = "my_watcher"
type = "file_watcher"
paths = ["./test_folder"]
pattern = "*.txt"
enabled = true

# Log when text files are created
[[rules]]
name = "text_file_alert"
description = "Notify when text files are created"
trigger = { type = "file_created", pattern = "*.txt" }
action = { type = "log", message = "New text file created!", level = "info" }
enabled = true

Need help with configuration? See the Configuration Reference for all available options.

3. Run the Engine

Open a terminal in the folder with engine.exe:

# Create a test folder (in the same folder as engine.exe)
mkdir test_folder

# Start the engine
engine.exe -c config.toml

# The engine is now running!

4. View the Dashboard

Open your browser and go to: http://127.0.0.1:9090

The dashboard is now ready and waiting for events. You'll see the connection status (green dot = connected).

5. Test It

In another terminal, create a test file:

echo "Hello World" > test_folder\test.txt

Watch as:

  1. The engine logs: [LUA] New text file created!
  2. The dashboard shows the event in real-time!
  3. The event counter increases

You'll see real-time events as they happen!

Next Steps

Try a Real Use Case

Once you've verified the engine works, try media automation:

  1. Copy config.media_automation.toml.example to config.toml
  2. Edit the title_contains value to match your preferred window (e.g., "nvim", "VS Code", "Firefox")
  3. Run the engine and switch between windows
  4. Your media will automatically pause when you leave that window, and resume when you return

Getting Started

Custom Actions

Monitoring & Debugging

Development

Running as a Windows Service

Run the engine in the background without keeping a terminal open. The service starts automatically on Windows startup.

Install the Service

Open an Administrator terminal in the folder containing engine.exe:

# Install the service
engine.exe --install

# Start the service
sc start WinEventEngine

Manage the Service

# Check status
sc query WinEventEngine

# Stop the service
sc stop WinEventEngine

# Uninstall (stops and removes)
engine.exe --uninstall

Notes:

  • Service starts automatically on Windows boot
  • Config file path must be absolute or relative to engine.exe location
  • Requires Administrator privileges for install/uninstall

Quick Reference

Common Commands

# View help
engine.exe --help

# Run with a config file
engine.exe -c config.toml

# Check if the engine is running
engine.exe --status

# Enable debug logging
engine.exe -c config.toml --log-level debug

# Dry run (see what would happen without executing)
engine.exe -c config.toml --dry-run

# Install as Windows Service (requires admin terminal)
engine.exe --install

# Start the Service (requires admin terminal)
sc start WinEventEngine

# Stop the Service (requires admin terminal)
sc stop WinEventEngine

# Uninstall as Windows Service (requires admin terminal)
engine.exe --uninstall

Example Configurations

Download Alert:

[[rules]]
name = "download_alert"
trigger = { type = "file_created", pattern = "*.exe" }
action = { type = "log", message = "Executable downloaded!", level = "warn" }

Auto-backup:

[[rules]]
name = "auto_backup"
trigger = { type = "file_modified", pattern = "*.docx" }
action = { type = "script", path = "backup.lua", function = "on_event" }

See Configuration Reference for more examples.

Quick Links

Clone this wiki locally