Getting started
Aitiy brings mouse gestures, hotkeys, screenshots and desktop tools together. Choose built-in actions for everyday tasks; no programming is required. This guide covers Windows.
Extract the entire download before running Aitiy.exe. Open Settings from the Aitiy menu in the notification area. Closing Settings leaves Aitiy running; use Pause or Exit in the tray menu when needed.
Choose your language, theme and enabled features in General, then configure each feature on its own page. Set startup separately in the tray menu. Start with the features you need.
Portable mode
1. Exit Aitiy. Beside Aitiy.exe, create a folder named .aitiy, including the leading dot.
2. Start Aitiy again. If this folder exists at startup, settings, language data and input statistics are stored there. Extracting the app onto a USB drive alone does not enable portable mode.
3. To move computers, exit the app and copy the whole application folder, including .aitiy. The destination must be writable.
Changing modes does not move existing data. To keep your settings, open General → Config Files, exit Aitiy, back up that folder and copy its contents into the new .aitiy folder. Moving the portable folder away while the app is closed restores the default data location on the next launch. The two locations are not merged automatically.
Aitiy/
├── Aitiy.exe
└── .aitiy/Mouse gestures and actions
Browse built-in actions such as Back, Copy, Close Window or Screenshot. In gesture settings, choose the trigger button, hold it while drawing a gesture, then release it to run its action. Check your configured bindings.
To add a rule, record a distinct gesture, select an action and save. Test in an ordinary window first. Avoid very similar gestures; review the drawing and recognition settings if matching is unreliable.
Global rules apply across apps; application rules target specific programs. Exclude apps where gestures get in the way. After editing an action or binding, check that the affected gestures still run the intended action.
Hotkeys, screen edges and schedules
Add a key combination on the Hotkeys page, choose an action and enable the rule. Avoid shortcuts already used by Windows or other apps. If it does not trigger, test another combination.
Screen edges and hot corners run actions when the pointer reaches a configured location and meets its dwell condition. Adjust positions and delays for your monitor layout to reduce accidental activation.
Scheduled tasks connect actions to trigger conditions. Save the action first, then add a task and configure its trigger. Check that it is enabled and review its execution status. Edit the linked action to change what it does.
Screenshots, annotations and OCR
Choose Screenshot in the action library and bind a gesture or hotkey. Drag to select a region, then use the toolbar to annotate, copy, save, pin or recognize text. Esc cancels; double-click inside the selection to copy it.
Continue annotating in the image editor, undo or redo changes, and zoom with the mouse wheel. Review the result before saving. OCR depends on text clarity; check important text after recognition.
For scrolling captures, start capture, scroll as instructed, then click to stop. Review the stitched preview before editing or saving. QR tools can recognize codes in screenshots or create a code from text.
Choose the OCR service in General. System OCR is the default; Network OCR uploads the selected image to ocr.aitiy.com for recognition.
Pinned images and editing
Pin an image on the desktop to keep a reference visible. Drag it to move it; double-click to switch between the full image and a cropped thumbnail.
Use the wheel to adjust opacity, arrow keys for small position changes, and Shift for larger steps. Right-click to copy, save, edit, switch thumbnail mode or close.
Save images you want to keep; pinning is useful for temporary reference. Once the editor is open, you can continue editing without keeping the original pinned window open.
Selection toolbar
Enable the selection toolbar in Settings. Select text to use configured buttons for copying, searching or translating. Adjust which buttons are enabled, their order, icons and actions.
You can also enable the double Ctrl+C trigger. If text capture fails in an app, first check whether ordinary copying works and whether the app is excluded.
Search and online translation open their respective services and pass selected text according to the action. Before using private text, check the button’s purpose and destination website.
Infinite Mouse
Run Aitiy on each Windows computer on the same local network and enable Infinite Mouse. Give devices recognizable names, refresh the device list, request pairing and accept it on the other computer.
After pairing, drag devices into a layout matching their physical positions. Move the pointer toward the corresponding screen edge to switch computers. Correct the layout if the direction feels wrong.
Enable clipboard synchronization if needed. If devices are missing or disconnected, check that both are online, the feature is enabled and the network allows communication. Then check Windows Firewall permissions for Aitiy.
Find mouse, key echo and input statistics
Find Mouse highlights the pointer when you double-tap Ctrl or shake the mouse, depending on your settings. Configure activation, appearance and timeout on its page for presentations or multiple monitors.
Key Echo displays keyboard and mouse input for recordings or demonstrations. Adjust its position and appearance. View keyboard and mouse usage on the Input Statistics page; enable collection when needed.
General also offers window dragging, volume control and sleep prevention. Read each option before enabling it. Turn off display aids or sleep prevention when your presentation is over.
Backup, migration and updates
Export configuration from General and keep it somewhere safe. Back up your current configuration before importing. A configuration export is not a full data backup: exit the app and copy the entire data folder to preserve language files and statistics too.
Exit before updating the application files, and keep the data folder. Portable users must retain .aitiy. After moving computers, review program paths, hotkeys, app rules and startup settings.
When upgrading from Alpha, old JavaScript actions cannot run directly. Back up first, reset the action library and gesture rules, then configure them again. Rewrite custom scripts in Lua.
Custom actions and advanced reference
Start with built-in actions. To combine operations, create or edit an action, enter its name, category and Lua script, then save and bind it to a gesture, hotkey, selection button, screen edge or scheduled task.
The script editor offers completion: arrow keys select a suggestion, Tab or Enter accepts it, Esc closes it, and Ctrl+Space opens it manually. Test a simple action before adding more steps.
Complete function descriptions and copyable examples are in the Lua API reference below on this page. Both the user guide and API reference follow the website language and support all 10 languages.
Troubleshooting
Nothing happens: check that Aitiy is running and not paused, then review feature switches, enabled rules, app exclusions and the bound action. Test in an ordinary app to identify app-specific restrictions.
Settings seem missing: check whether the application moved or a .aitiy folder was created or removed. Aitiy chooses its data folder at startup and does not merge locations. Locate and back up your original data first.
Conflicts or accidental activation: change the hotkey, simplify gestures, increase edge dwell time or exclude an app. If the issue persists, report your Aitiy and Windows versions, steps to reproduce and expected result.
Aitiy Lua action API
Windows action scripts use Lua and the aitiy.* desktop API.
Writing actions
Create an action under Settings → Actions, assign a unique ID and category, enter Lua, save, then bind it to a gesture, hotkey, selection button, screen edge or schedule. Call functions with a dot, not a colon. Names follow aitiy.domain.verb_object: get reads, set assigns, toggle switches, adjust changes relatively, and is returns boolean. Optional settings use an options table. Unknown options and invalid types, enums or ranges raise errors.
Native calls suspend and resume the action coroutine in order. Handle failures with pcall. Ordinary commands return nil unless documented otherwise. Submission does not imply completion in another application. Actions have a 120-second wall limit including waits, memory/instruction budgets, and a maximum of 64 concurrent jobs. Timeout does not undo submitted native work. io, os, package, debug, dynamic loading and user coroutines are unavailable.
aitiy.keyboard.send('Ctrl+C')
aitiy.ui.notify('Copied', {duration_ms=2000, placement='center'})
local ok, percent = pcall(aitiy.system.get_brightness)
if ok then aitiy.ui.notify(tostring(percent) .. '%') endAction context
context is a trigger-time snapshot. Editing it does not change the captured native target. Optional window_handle defaults to that target; invalid handles fail rather than redirecting to another foreground window. Keyboard input, accessibility scrolling and simulated copying still affect the application receiving input at execution time.
| Field | Meaning |
|---|---|
window_handle | HWND integer; 0 when unavailable |
process_id | Target process ID |
window_title / window_class | Window title and class |
process_name / process_path | Process filename and full path |
window_region | Window region {x, y, width, height} |
pointer_start / pointer_end | Trigger start/end points {x, y} |
selection_region | Optional capture region supplied by the trigger, otherwise nil |
selected_text | Text supplied by the trigger, possibly empty; use selection.get_text for active retrieval |
All coordinates are physical virtual-desktop pixels; negative coordinates are valid. Regions use integer x/y/width/height with positive dimensions. Noninteractive capture/OCR regions must fit entirely within the virtual desktop, with each dimension at most 32768 and at most 32 × 1024 × 1024 pixels. Images accept PNG data URLs, not file paths or HTTP URLs. The URL limit is 180 MiB, but Lua memory limits can reject large results earlier. Window creation is not completion of user editing.
API reference
A question mark in a signature marks an optional argument; it is not Lua syntax.
| API | Parameters and result |
|---|---|
aitiy.shell.open(target, options?) | Launch a program, file or URL. options: arguments (Windows argument string, default empty), run_as_admin and hidden (booleans, default false). Quote paths within arguments yourself. target is not a whole command line. Does not wait for process exit. |
aitiy.keyboard.send(keys, options?) | Send a key chord such as Ctrl+C, Win+Tab or VolumeUp using the existing key-name parser. options.legacy is a boolean, default false (SendInput). Set true to use legacy keybd_event, holding keys for about 30ms before release, for applications that do not recognize the default method. Example: aitiy.keyboard.send('Ctrl+C', {legacy=true}). |
aitiy.keyboard.is_down(key_code) | Windows virtual key code, integer 1–254 (Ctrl = 0x11). Returns boolean; key names are not accepted. |
aitiy.mouse.click(button?) | Click left (default), right or middle at the current pointer position. |
aitiy.mouse.move_to(x, y) | Move to absolute physical screen coordinates. |
aitiy.mouse.highlight() | Start the automatically closing pointer highlight; returns true. |
aitiy.clipboard.get_text() | Return clipboard text, or an empty string. |
aitiy.clipboard.set_text(text) | Write a string to the clipboard. |
aitiy.selection.get_text(options?) | Use text captured by the trigger; otherwise simulate Ctrl+C and restore the previous clipboard text. options.legacy is a boolean, default false; set true to send the copy shortcut using legacy keybd_event, for example aitiy.selection.get_text({legacy=true}). An application that ignores copying may leave the previous clipboard text as the result. |
aitiy.text.encode_base64(text) | Encode UTF-8 bytes as Base64. |
aitiy.text.encode_url(text) | Percent-encode a URL component; spaces become %20. |
aitiy.i18n.get(key) | Read a localized UI string by key. This is not machine translation. |
aitiy.window.close(window_handle?) | Request that the target window close. |
aitiy.window.close_similar(window_handle?) | Close similar windows using Aitiy's existing matching rules. |
aitiy.window.minimize(window_handle?) | Minimize the target window. |
aitiy.window.toggle_maximized(window_handle?) | Toggle between maximized and restored. |
aitiy.window.set_topmost(enabled, window_handle?) | Set a definite topmost state; enabled must be boolean. |
aitiy.window.toggle_topmost(window_handle?) | Toggle the target's actual topmost state. |
aitiy.window.hide_to_tray(window_handle?) | Hide the target behind a managed tray icon. |
aitiy.window.restore_from_tray() | Restore the most recently hidden managed window. |
aitiy.window.toggle_tray_windows() | Restore all managed hidden windows, or hide the foreground window if none are hidden. |
aitiy.window.is_fullscreen(window_handle?) | Return boolean for the target window. |
aitiy.window.crop_lock() | Start interactive crop locking; choose the target window in the selection UI. No target window is required when invoking the action. |
aitiy.window.clear_crop_locks() | Release every crop lock and restore original windows; returns true. |
aitiy.window.post_message(message_id, options?) | Post a Win32 message. options: window_handle (default action target), wparam=0, lparam=0. message_id is an unsigned 32-bit integer; lparam may be negative. Does not wait for processing. |
aitiy.window.scroll_to(edge) | top or bottom; first scroll the focused accessibility container, then fall back to Home / End if unavailable or unsuccessful. Returns true after scrolling succeeds or the key request completes; keys target the current focus and may move the caret in an input field. |
aitiy.screen.select(options?) | Open interactive capture. options: mode = capture (default), pin or ocr; region = optional initial region. Defaults to the trigger's region. Returns nil after opening, without waiting for selection; does not return an image. |
aitiy.screen.capture(region) | Capture a region without UI; returns {data_url, width, height}, where data_url is a PNG data URL. |
aitiy.screen.recognize_text(region) | System OCR on a region without UI; returns text, empty string when successful but empty, or raises an error. Does not change the clipboard or use network OCR. |
aitiy.screen.get_work_area() | Return the pointer monitor's work area as {x, y, width, height}, excluding reserved areas such as the taskbar. |
aitiy.image.pin(image, options?) | image is a capture result or PNG data URL. options: x and y, each defaulting to the pointer coordinate. Pin at original physical size; returns true when created. |
aitiy.image.edit(image) | Accept the same image input and open the editor; returns true when created. |
aitiy.system.get_brightness() | Return an integer 0–100, or raise an error when unavailable. Not a per-monitor query. |
aitiy.system.set_brightness(percent) | Set integer percent 0–100 and show a brightness tip. Returns true when submitted, without hardware completion guarantees. 100 means maximum brightness. |
aitiy.system.adjust_brightness(delta_percent) | Integer delta_percent -100–100. Read and submit in one UI operation, clamp to 0–100, show a brightness tip, and return the target percentage. If reading fails, show an unavailable tip and raise an error. |
aitiy.system.is_dark_mode() | Return whether Windows uses a dark system theme. |
aitiy.system.set_theme(theme) | Set the Windows theme to dark or light. |
aitiy.system.toggle_theme() | Toggle the Windows system theme. |
aitiy.system.toggle_desktop_icons() | Toggle desktop icon visibility. |
aitiy.app.open_settings() | Open native settings. |
aitiy.app.open_data_folder() | Open the active user data folder, including portable mode. |
aitiy.app.toggle_paused() | Toggle Aitiy's paused state. |
aitiy.app.toggle_tray_icon() | Toggle the main Aitiy tray icon. |
aitiy.app.exclude_target(rule_type?) | Omit rule_type for a dialog; process, window or class applies that exclusion rule to the action target. |
aitiy.app.exit() | Request application exit. Subsequent script steps are not guaranteed to run. |
aitiy.config.get(path) | Read a dot-separated configuration path, such as key_echo.enabled. |
aitiy.config.set(path, value) | Persist a value and synchronize UI; nil is not accepted. New empty tables are objects; nonempty contiguous integer-index tables are arrays. Arrays read from native results retain their array type when cleared or written back unchanged. |
aitiy.config.toggle(path) | Only existing boolean fields are supported. Read and toggle in one UI operation; return the new boolean. |
aitiy.state.get(key, default_value?) | Read a process-local temporary value, or default_value (nil by default). |
aitiy.state.set(key, value) | Set a temporary value; nil deletes it. Shared by actions, lost on exit. Multiple get/set calls are not a transaction; prefix keys with the action ID. |
aitiy.ui.notify(text, options?) | options: duration_ms=3000 (integer 1–120000), placement=bottom_right, center or fullscreen. |
aitiy.ui.show_qrcode(text) | Display a QR code. UTF-8 text is limited to 512 bytes, truncated at character boundaries. |
aitiy.sleep(duration_ms) | Integer milliseconds 0–120000. Suspend this action without blocking UI or other actions. |
Default action library
The 83 defaults are editable Lua compositions using the same public API. Categories follow user tasks rather than API modules. Category IDs are lowercase; the UI localizes their labels and permits custom names.
| Category | Purpose |
|---|---|
editing | Copy, paste, Escape and Delete |
browser | Navigation, refresh and tabs |
window | Close, maximize, topmost and managed tray windows |
capture | Screenshots, OCR, pins, work-area capture and crop locks |
text | Search, online translation, Base64 and QR codes |
system | Desktop, volume, brightness, theme and sleep prevention |
tools | Program launching, file location, ping, pointer highlight and application-specific commands |
aitiy | Settings, data folder, pause, exclusions and tray icon |
reminders | Notifications and scheduled reminders |
custom | User scripts and pointer-input examples |
The library provides 83 editable actions. brightness_max sets brightness to 100%. Action IDs connect scripts to gestures, hotkeys, selection buttons, screen edges and schedules; renaming an action updates its references. Bind application-specific commands only to the intended application, and edit example coordinates before use.
Examples
local region = aitiy.screen.get_work_area()
local image = aitiy.screen.capture(region)
aitiy.image.pin(image, {x=region.x, y=region.y})
aitiy.image.edit(image)local text = aitiy.screen.recognize_text({x=100, y=100, width=400, height=200})
if text ~= '' then
aitiy.clipboard.set_text(text)
aitiy.ui.show_qrcode(text)
endif not aitiy.window.is_fullscreen(context.window_handle) then
aitiy.window.toggle_topmost(context.window_handle)
end
local enabled = aitiy.config.toggle('key_echo.enabled')
aitiy.ui.notify(tostring(enabled))AI help
Ask the AI to read https://aitiy.com/llms.txt and https://aitiy.com/docs.html first. Request a complete current Windows Lua action using aitiy APIs, named options, physical coordinates and pcall for errors. Request setup, binding and verification steps. Do not invent undocumented APIs.