Documentation

Know what you’re building.

AppleScript had 40 years. Windows had nothing. Until now. WinScript-lang gives Windows automation a natural, structured language designed for humans and AI agents.

View architecture Open GitHub repo Jump to MCP tools

At a glance

WinScript is a pipeline, a language surface, and an agent interface all at once. This reference explains the runtime path and the primitives that make that possible.

Core identity: WinScript is a high-level scripting language for Windows automation. It replaces brittle coordinate automation with explicit command resolution, structured execution, and backend-specific integrations.
Why it matters: The language is intentionally readable enough for humans while remaining structured enough for AI agents to validate and run safely.

Architecture pipeline

Grammar to backend, with dictionaries in the middle.

Grammar

A Lark PEG grammar parses `tell/end tell` blocks and natural-syntax instructions.

The grammar gives WinScript a readable surface while still preserving enough structure for deterministic parsing.

AST

Parsed source is transformed into explicit dataclass-style nodes.

The AST normalizes human-friendly syntax into a machine-friendly representation the runtime can reason about.

Resolver

Natural commands are matched to `.wsdict` definitions.

This is where community dictionaries become executable capability maps instead of ad hoc prompt instructions.

Dispatcher

Resolved actions are routed to the correct backend.

A single script can stay high-level while the dispatcher decides which adapter should fulfill each command.

Backends

CDP is active today, with COM and UIA on the roadmap.

Chrome and Electron apps are ready now; Office and native Win32 support expand the same model across Windows.

Core constructs

The smallest useful language surface.

tell

tell application "Chrome"

Enters the context of an application and scopes the actions that follow.

set

set url to "https://example.com"

Captures state in readable variables that can be reused later in the script.

return

return auth_state

Emits a final value back to the caller or calling agent.

wait

wait until loaded

Coordinates timing without forcing users into fixed sleeps or brittle sequencing.

try/catch

try ... catch err

Makes automation resilient by expressing fallback behavior alongside the happy path.

Benchmarks snapshot

The project already has meaningful test coverage and performance targets that point toward a serious runtime.

Tests130

Modules10

ParsingSub-ms

MCP integration

Five tools that let agents inspect, validate, and run.

run_winscript

Execute source provided inline.

Best for agents or UIs that assemble scripts dynamically at runtime.

run_winscript_file

Execute a script stored on disk.

Keeps larger workflows versionable and easier to reuse across teams.

list_available_apps

Discover installed or known `.wsdict` targets.

Lets an agent inspect the current capability surface before choosing a path.

get_app_commands

Inspect the command vocabulary for one application.

Turns each supported app into a queryable interface instead of a hidden implementation detail.

validate_script

Parse-check a script without running it.

Ideal for editor integrations, agent planning, and safe preflight validation.

Language primitives

Control flow, timing, state, and comparison.

tell/end tell

if/then

try/catch

set

return

wait

contains

is greater than

& concatenation

WinScript example

tell application "VS Code"
    set project_name to "win-lang-site"
    open folder "C:/projects/" & project_name
    wait 1 second
    return "workspace_ready"
end tell

.wsdict format

Open dictionaries unlock app support without changing the parser.

`.wsdict` is a YAML-based open dictionary format.
It maps readable commands to backend-specific methods.
The runtime can gain new app support without rewriting the core parser or dispatcher.

.wsdict example

app: Chrome
backend: cdp

commands:
  open:
    mapsTo: CDP.Page.navigate
    args:
      url: string

  click button:
    mapsTo: CDP.DOM.click
    target:
      role: button

Technical framing

What makes WinScript different from brittle desktop automation.

Agent-first runtime

Validation, app discovery, command introspection, and execution are exposed through MCP.

Backend strategy

CDP is live for Chrome and Electron apps, with COM and UIA expanding the same mental model across Windows.

Reference diagram

One script, many coordinated layers.

Execution map

From natural command to backend call

The runtime stays readable on top by moving complexity into resolvers and dispatchers underneath.

WinScript sourcetell / set / wait

Resolver.wsdict definitions

DispatcherCDP / COM / UIA