`@simular-ai/simulang-js`

Node.js bindings for simulang-rs, a Rust crate published by Simular, built with napi-rs. Provides high-level primitives for desktop automation — keyboard and mouse input, screenshots, clipboard access, audio capture, accessibility-tree inspection, and more — exposed through idiomatic JavaScript. Ships TypeScript definitions auto-generated from the Rust source, so the types always match runtime behavior.

Install

npm install @simular-ai/simulang-js

Prebuilt native binaries are published for:

Platform	Architecture
macOS	`aarch64` (Apple Silicon), `x86_64`
Windows	`x86_64`, `aarch64`
Linux	`x86_64`, `aarch64` (glibc)

Node.js 20 or newer is required. If your platform isn’t covered, see Building from source.

Optional — install the log viewer

The log-window.mjs example uses @simular-ai/simulang-log-viewer, which is declared as an optional peer dependency and not installed by default. Install it only if you want to run that example or use the same pattern in your own code:

npm install @simular-ai/simulang-log-viewer

Usage

Try the included google_search.mjs example — it opens Google in Chrome, enables the accessibility tree, takes a screenshot, and displays it:

# With the simulang CLI (no local install needed):
npm install -g @simular-ai/simulang
simulang run examples/google_search.mjs

# Or directly with Node.js if you have simulang-js installed locally:
node examples/google_search.mjs

API documentation

Browse the API reference for more details. A bleeding-edge preview of HEAD on main is also published to GitHub Pages between releases.

Using with Claude Code

This package ships a short CLAUDE.md inside the npm tarball that points Claude Code at index.d.ts as the source of truth for the API and adds a few cross-cutting notes that types alone can’t express (lifetime rules, coordinate system, etc.). Wire it into your project’s CLAUDE.md with:

npx simulang-init-claude          # appends to <project>/CLAUDE.md (creates it if missing)
npx simulang-init-claude --user   # appends to ~/.claude/CLAUDE.md instead
npx simulang-init-claude --check  # report status, don't write

The added line is a single @./node_modules/@simular-ai/simulang-js/CLAUDE.md import inside a sentinel-delimited block — safe to re-run, no-op when already present.

Relationship to `simulang`

@simular-ai/simulang is a CLI that runs desktop automation scripts (.ts, .js, .simulang) using this package. It bundles simulang-js and re-exports the full API to scripts, so you can write and run automation scripts without a build step:

npm install -g @simular-ai/simulang
simulang run my-script.js

simulang-js is the underlying primitive library; simulang is the batteries-included script runner built on top of it. If you are embedding desktop automation into your own Node.js application, depend on simulang-js directly. If you just want to run standalone automation scripts, simulang is the easier starting point. You can also point simulang at a local simulang-js checkout during development:

simulang run --simulang-js=/path/to/simulang-js my-script.js

Enumerations

Enumeration	Description
AriaRole	Cross-platform ARIA / Playwright role. Used as the `role` field on accessibility snapshots and as the search key in [`AccessibilityTree::find`].
Button	Represents a mouse button.
Coordinate	Specifies if coordinates are relative or absolute.
Direction	The direction of a button event.
FocusPolicy	Focus behavior when opening an application.
Key	Represents a keyboard key.
TraversalOrder	Tree traversal order for `AccessibilityTree.find()`.
Visibility	Visibility behavior when opening an application.

Classes

Class	Description
AccessibilityNode	A node in the platform accessibility tree. Thin binding for `simulang_rs::AXNode` (macOS `AXUIElement` / Windows UIA element / Linux AT-SPI accessible).
AccessibilityTree	Accessibility tree bound to a specific window. Provides snapshot and ref-based actions for desktop automation (Windows UIA).
App	Represents an application that can be opened.
AskModel	A free-form chat-completions LLM (optionally vision-capable) — the JS analogue of the `ask` primitive.
AudioOutput	Handle to an open audio output device. Must be kept alive for playback to continue — when dropped all associated `Player`s stop producing sound.
Clipboard	Contains functions to read and write the clipboard.
Directory	Represents a directory handle.
File	Represents a file handle.
GroundingModel	A visual-language grounding model that can locate concepts on images.
Image	Represents an image.
Instance	Represents an opened application instance.
KeyboardController	Contains functions to simulate key presses/releases and to input text.
LoopbackSource	A loopback capture source that records system audio output (what the user hears through their speakers or headphones).
MouseController	Contains functions to control the mouse and to get the location of the cursor. A cartesian coordinate system is used for specifying coordinates. The origin is located in the top-left corner of the current screen, with positive values extending along the axes down and to the right of the origin point and it is measured in pixels. The same coordinate system is used on all operating systems.
Player	Handle to a device that outputs sounds.
SamplesBuffer	A buffer of samples treated as a source.
Screen	Represents a physical display/screen.
Screenshot	Represents a screenshot capture.
ScreenshotCoordinateType	Describes how `(x, y)` coordinates passed to `Screenshot.toGlobalPhysicalPixels` should be interpreted.
SttModel	A speech-to-text model that can transcribe audio.
System	Provides system-wide operations.
Window	Handle to an on-screen window. Constructed via [`Window.all`] or [`Window.allForPid`] and exposes read-only metadata (`title`, `pid`) alongside basic actions (`minimize`, `maximize`, `close`).

Interfaces

Interface	Description
AccessibilityNodeJs	-
BoundingBox	Axis-aligned rectangle. `right` and `bottom` are exclusive (Playwright / DOM convention), so the box covers `[left, right) × [top, bottom)`.
JsLogRecord	A single log entry forwarded to the JS callback.

Functions

Function	Description
ariaRoleToString	Lowercase ARIA name for a role — matches the form used in snapshot output and accepted by `AccessibilityTree.find()`.
enableAccessibilityForFrontmostApp	Enables the accessibility tree for the frontmost application.
hasScreenCapturePermission	-
initLogger	Initialize the logger.
keyFromString	Convert a string representation into a `Key`.
legacyOpen	Legacy helper used by Electron to open an app or URL.
legacyTakeScreenshot	Legacy helper used by Electron to capture a screenshot as base64.
readFile	Reads a file and returns its trimmed contents.
screenshotCropped	Takes the screenshot of a cropped region of the workspace.
screenshotFull	Takes the screenshot of the entire selected screen
writeFile	Writes content to a file, returning the absolute path written to.

​@simular-ai/simulang-js

​Install

​Optional — install the log viewer

​Usage

​API documentation

​Using with Claude Code

​Relationship to simulang

​Enumerations

​Classes

​Interfaces

​Functions