Documentation Index
Fetch the complete documentation index at: https://docs.simular.ai/llms.txt
Use this file to discover all available pages before exploring further.
@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
| Platform | Architecture |
|---|
| macOS | aarch64 (Apple Silicon), x86_64 |
| Windows | x86_64, aarch64 |
| Linux | x86_64, aarch64 (glibc) |
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
@./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 Players 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. |
