win-nav

Stable CLI + MCP bridge for fluid QA testing and lawful, assisted desktop automation on native Windows applications (Windows Forms .NET 8, WPF, WinUI 3, and hybrid apps with WebView2, packaged via Velopack) via Microsoft UI Automation.

🔗 Sister Project Reference

win-nav is the Windows Desktop counterpart to pwa-nav (designed for Firefox PWAs).

Both projects share the exact same clean design patterns, JSON Schema 2020-12 contracts, ephemeral eN snapshot references, semantic @id targets, dry-run safety gates, and MCP stdio tool interfaces. If you already know how to drive pwa-nav for web apps, you already know how to drive win-nav for native desktop software.

Related MCP server: opencode-gui-bridge

💡 Why win-nav?

Classic desktop automation tools rely on:

• Fragile pixel coordinates: Breaks immediately on display scaling (DPI 125%/150%), resolution changes, or OS theme shifts.

• Slow, unreliable OCR: High token overhead, prone to misreading text.

• External heavyweight drivers: WinAppDriver / Appium requiring complex setup, elevation, or developer mode.

win-nav takes a better path:

1. Direct UI Automation (UIA3 / FlaUI): Attaches directly to the application's native accessibility tree. Reads real AutomationId, Name, ControlType, and patterns without modifying the target application.

2. Velopack-Native: Seamlessly detects and resolves apps installed under %LocalAppData%\<App>\current\<App>.exe.

3. Traverses Embedded WebViews: Interacts effortlessly with embedded Chromium / Microsoft Edge WebView2 controls inside desktop forms.

4. Token-Efficient Screen Maps: Pre-mapped windows expose clean semantic @id targets (@BtnAbrirTicket), allowing agents to operate in ~200 tokens per action without taking full DOM/UIA trees.

5. Dry-Run by Default: Safe pair-programming; all mutations require explicit --armed approval.

🔍 Live-Verified Example (Velopack & WinForms)

win-nav has been validated against real enterprise .NET 8 Windows Forms applications packaged with Velopack (such as Sigestran.exe). Here is a real sample of controls extracted in milliseconds via UI Automation:

Type            AutomationId         Name                 ClassName
----            ------------         ----                 ---------
Button          BtnAbrirTicket       BtnAbrirTicket       C1.Win.Input.C1Button
Button          BtnTicketsPendientes BtnTicketsPendientes C1.Win.Input.C1Button
Button          BtnControlTower      BtnControlTower      C1.Win.Input.C1Button
Button          BtnRefreshCashe      BtnRefreshCashe      C1.Win.Input.C1Button
Pane            CbSelectUser                              WindowsForms10.Window...
  └ Edit        Search                                    WindowsForms10.Edit
  └ Button      BtnDropDown                               WindowsForms10.Button
Pane            Manual Usuario       Manual Usuario       Chrome_WidgetWin_1 (WebView2)
  └ Hyperlink                        Logo Manual Usuario  BrowserRootView

🚀 Quick Start

Prerequisites

• Windows 10/11

• Node.js 22 LTS

• .NET 8 SDK / Runtime

Installation

git clone https://github.com/SebassContreras/win-nav.git
cd win-nav
pnpm install
pnpm build

🛠️ CLI Usage

1. Interactive Snapshot Loop (Exploration)

Capture active controls into .agent/snapshot.json:

# Snapshot active process
win-nav snapshot -p Sigestran -i

# Inspect available controls (e1, e2, ...)
# Click an element (dry-run preview)
win-nav click e1

# Armed execution (actually executes click)
win-nav click e1 --armed

2. Screen Map Navigation (Semantic)

Drive known screens using declarative @id selectors:

# Inspect current window capabilities (~200 tokens)
win-nav snapshot --screen

# Click semantic button
win-nav click '@BtnAbrirTicket' --armed

# Fill text into an edit field
win-nav fill '@Search' "administrador" --armed

# Run a declarative multi-window journey
win-nav journey nuevo-ticket usuario="Juan" --armed

PowerShell Tip: Always wrap semantic targets in single quotes ('@BtnAbrirTicket') to prevent PowerShell from interpreting @ as a splatting variable.

🤖 Model Context Protocol (MCP) Server

Connect win-nav directly to Claude Desktop, Antigravity, Cursor, or any MCP client.

Configuration (mcpServers)

{
  "mcpServers": {
    "win-nav": {
      "command": "node",
      "args": ["C:/Users/scontreras/Documents/GitHub/win-nav/dist/mcp.js"]
    }
  }
}

Exposed MCP Tools

• win_snapshot: Captures interactive UI elements for a target window.

• win_click: Clicks control by ref (e1) or semantic ID (@id), requiring armed: true.

• win_fill: Types text into an edit box or combo.

• win_qa: Evaluates assertions (assert:visible, assert:text).

• win_learn: Learns a new window and adds it to screens/<app>.screens.json.

🔒 Safety & Security

• Strict Dry-Run Default: Mutations require explicit --armed flag.

• Sensitive Fields Barrier: Password controls (IsPassword == true) throw exit code 11 (sensitive_target) and instruct the user to type them manually.

• Emergency Kill-Switch: The presence of file .agent/kill or env WIN_NAV_KILL_SWITCH immediately terminates execution (exit code 7).

• Process Allow-List: Navigation and attachment are gated by .agent/allow.json (exit code 6).

📋 Exit Codes

📄 License

MIT © Sebastian Contreras