Kimetra is a keyboard and mouse automation library for Node.js. It presses keys, types text, moves the pointer, clicks and scrolls by calling the OS input APIs directly: SendInput on Windows, CGEvent on macOS and uinput on Linux. I published 1.0.0 in June 2025 and 2.2.0 in October 2026, and a lot of the time in between went into finding out what my own code didn't do.
Version 1 worked on my machine
I started it because of installs. The libraries I had used built a native addon during npm install, so every machine needed Python 3 and a C++ toolchain before a single key got pressed. I wanted npm i to compile nothing. Kimetra ships prebuilt binaries for each platform, and a post-install step deletes the ones your machine can't use, so it ends up at 188 KB with no dependencies.
Version 1 was keyboard only, and without meaning to I had written a Windows library. ctrl, shift, alt and meta only existed in the Windows key map, so on macOS and Linux, copy, paste and every other shortcut silently did nothing. macOS also threw away every event when the app running the script didn't have Accessibility permission, again without any error.
Moving Linux from X11 to uinput
The first Linux backend used X11. On Wayland, input sent through X11 only reaches apps running under XWayland, and Ubuntu and Fedora both default to Wayland now. In March 2026 I deleted the X11 code and rewrote the Linux side on uinput.
uinput creates a virtual input device in the kernel, and apps see it as one more keyboard plugged in. That's why it works the same on X11 and Wayland. The downside is a one-time permission setup:
echo 'KERNEL=="uinput", GROUP="input", MODE="0660"' | sudo tee /etc/udev/rules.d/99-kimetra.rules sudo usermod -aG input $USER If the permission is missing, Kimetra throws an error with these instructions in it. I wish more native packages did that.
uinput has limits I haven't worked around yet. It sends scan codes, so typeText on Linux can only type what a US QWERTY layout produces. It also can't see the screen, so absolute mouse moves aren't available on Linux. Relative moves, clicks and scrolling work.
The 2.0 rewrite
2.0.0 came out in August 2026. I called it a correctness release in the changelog, which was the polite way to say a lot of 1.x was broken. Some of what I found:
- The ESM entry point used
require, soimport { Kimetra } from 'kimetra'threw every time. It had never worked. -
waitinside a sequence read the wrong field and ignored its duration. Every wait slept 700 microseconds. - A macro cleared itself after
exec(), so it could only run once. -
pressKeyscheckeddelayinstead ofinterval, so the interval was never applied. -
cleanup()did nothing, because no addon exported aCleanupfunction.
Nobody had opened a GitHub issue about any of these. That probably says more about how many people were using it than about the bugs.
I also cut the API down. 1.x had aliases like arrowUp, altF4, winKey and taskManager, plus a whole cmd* family. 2.0 exports Kimetra, Kimacro and Key, and keys are plain strings that mean the same thing on every OS. There is now a test suite that runs in CI on all three platforms without sending a single key event.
The change that did the most for speed was moving execution into the addon. Before 2.0, a three-key hotkey crossed from JavaScript into native code about thirteen times. Now a list of actions compiles into one flat buffer and runs as one native call:
await ki.executeSequence([ { type: 'hotkey', keys: ['alt', 'tab'] }, { type: 'wait', duration: 500000 }, // microseconds by default { type: 'text', text: 'Sequence text' }, { type: 'key', key: 'enter' }, { type: 'click', button: 'left' } ]); setTimeout was too slow for this
Once batches ran natively, the waits between actions were the next problem. On Windows, setTimeout is coarse. In my benchmark a 1 ms setTimeout fired 14.5 ms late at the median.
1.x busy-waited the last 100 ms of every wait, which keeps a CPU core at full load for those 100 ms. In 2.0 each wait computes an absolute deadline first, sleeps on the OS timer until 1.2 ms before it, then spins for the rest. Windows uses a high resolution waitable timer, Linux uses clock_nanosleep and macOS uses mach_wait_until. In the same benchmark, Kimetra's 1 ms wait was never more than 0.04 ms late.
All of this is synchronous. The methods return promises so await reads naturally, but a one second wait inside a sequence blocks the event loop for one second. Long pauses belong in JavaScript.
How it compares to robotjs and nut.js
For 2.2 I wrote a benchmark that sends real input to a browser page. The page timestamps every event it receives and checks that it got exactly what was sent. The scenarios are typing a sentence, filling a form, a game macro with overlapping key holds, and a mouse workflow with glides, clicks, a drag and scrolling. These are medians of 3 runs on Windows 11, Node 22 and Chrome 152:
| Timing error | Time added | Installed size | |
|---|---|---|---|
| Kimetra 2.2 | 0.9 ms | 0.35 s | 188 KB, 1 package |
| robotjs 0.9.1 | 11.0 ms | 1.66 s | 2.6 MB, 3 packages |
| nut.js 4.2.6 | 25.5 ms | 4.87 s | 28.6 MB, 125 packages |
Timing error is how far each gap between two events landed from the planned gap. Time added is the overhead on top of 15.6 seconds of scripted scenarios. nut.js here is the @nut-tree-fork/nut-js package, and every library had its own built-in delays set to zero. Their defaults are 10 ms per event for robotjs and 300 ms per key for nut.js.
All of that gap comes from running a whole scenario as one native call. If you call Kimetra one action at a time with setTimeout in between, it lands at 10.6 ms, right next to robotjs. Raw throughput is the same for both, about 4,300 key taps a second, because that time is spent inside the OS.
nut.js also does screen capture, image search and window management. Kimetra only sends input, which is how it stays this small, so if you need those features nut.js is the better pick. The drivers for each library are in the repo's bench folder if you want to check how I called them.
Trying it
npm install kimetra import { Kimetra } from 'kimetra'; // yes, this works now const ki = Kimetra(); await ki.pressHotkey(['ctrl', 'c']); await ki.typeText('Hello from Kimetra'); await ki.moveMouseBy(200, 0, 250000); // move right, gliding over 250 ms await ki.click(); ki.cleanup(); There is also a CLI, and a whole chain of commands compiles into one native call:
npx kimetra hotkey alt+tab wait 200 type "hi" key enter On macOS, give Accessibility permission to whatever runs the script, such as Terminal, iTerm or VS Code. Windows needs no setup, but a normal process can't send input to a window running as administrator. Prebuilt binaries cover Windows x64 and ia32, macOS x64 and arm64, and Linux x64 and ia32 on Node 16 or newer. There is no linux-arm64 or Alpine build yet.
Absolute mouse moves on Linux are the biggest gap left. If you know a clean way to get the pointer position under Wayland, I'd like to hear it in the comments or on GitHub.
- GitHub: https://github.com/saad-devx/kimetra
- npm: https://www.npmjs.com/package/kimetra
- Project page and benchmarks: https://saad.to/work/kimetra
