Helix Computer Use

Helix Control

Helix Control is a plug-in Windows computer-use stack for agents. It gives Codex and other MCP-capable agents three coordinated execution lanes:

• a managed browser lane for DOM-native work through Chrome DevTools and Playwright MCP
• a native desktop lane for Windows UI, browser chrome, prompts, and file pickers
• a dynamic-control lane for moving, animated, drag-validated, or timing-sensitive surfaces

The stack is designed to be installed once, reused across projects, and adapted through MCP configuration rather than one-off automation scripts.

[中文说明](README.zh-CN.md)

Architecture

flowchart LR
  A["Dedicated Managed Browser\nCDP endpoint, default localhost:9223"] --> B["chrome-devtools MCP\nDOM reads, clicks, navigation"]
  A --> E["Playwright MCP\nCDP fallback on the same browser"]
  B -->|native prompt, browser chrome, visible mismatch| C["windows_desktop MCP\nUIA, screenshots, file pickers"]
  E -->|native prompt, browser chrome, visible mismatch| C
  C -->|moving or timing-sensitive target| D["dynamic_control MCP\nhigh-frequency capture + input loop"]
  D -->|surface stabilizes| C
  C -->|DOM lane is healthy again| B

The routing rule is simple: start on the lightest capable lane, escalate only when the visible surface proves it is needed, then step back down as soon as the surface is stable again.

What You Get

| Lane | Use it for | Primary entrypoints | | --- | --- | --- | | Browser | DOM reads, clicks, forms, scrolling, navigation | chrome-devtools MCP attached to a dedicated managed browser endpoint | | Browser session | Dedicated managed Chrome profile for stable agent control | scripts/start-managed-chrome.ps1, scripts/stop-managed-chrome.ps1 | | Playwright MCP | Preferred Playwright fallback on the same managed browser | mcp_servers.playwright / @playwright/mcp --cdp-endpoint= | | Managed Playwright CLI | Scripted Playwright fallback when MCP is unavailable | scripts/invoke-managed-chrome-playwright.ps1 | | Persistent browser | Optional Playwright-backed browser MCP when you want a repo-owned profile | src/browser-control-mcp.mjs | | Desktop | Native prompts, file pickers, browser chrome, weak-UIA apps, UTF-8-safe text input, batched relative clicks, visible acceptance checks | src/windows-desktop-mcp.mjs, scripts/desktop-control.ps1 | | Dynamic | Moving targets, canvas surfaces, drag validation, high-frequency control | src/dynamic-control-mcp.mjs, scripts/dynamic_surface_browser_pipeline.py |

Quick Start

Requirements:

• Windows 10 or 11
• Google Chrome
• Node.js 20+
• Python 3.10+
• PowerShell 5.1 or later

Install Node dependencies:

npm install
npm run check

Create the Python environments used by the desktop and dynamic lanes:

npm run setup:python

Start the managed Chrome endpoint:

npm run managed:chrome:start

Smoke-test the desktop lane:

npm run desktop:health

Install Helix Control as the local Codex plugin and canonical MCP source:

npm run install:codex

Restart Codex Desktop after installation so plugin, skill, and MCP discovery reload.

MCP Setup

For Codex, add or import the provided .mcp.json from the repository root. It registers:

• chrome-devtools against a dedicated managed browser endpoint
• playwright against the same managed browser endpoint
• browser_control for the optional repo-owned Playwright session
• windows_desktop for native Windows control
• dynamic_control for high-frequency dynamic surfaces

The default examples use http://127.0.0.1:9223 because a local fixed CDP port is easy for MCP tools to attach to. That port is not a product requirement. You can start the managed browser on another local port and pass the matching URL to the installer:

powershell -NoProfile -ExecutionPolicy Bypass -File scripts/install-codex-plugin.ps1 -ManagedChromeUrl http://127.0.0.1:9333

For machine-wide use, prefer the plugin installer:

npm run install:codex

It registers the local marketplace helix-control, enables helix-control@helix-control, and points global MCP entries at this repository. See [Codex Plugin](docs/CODEX_PLUGIN.md).

The managed browser profile is local to this repository by default:

.profiles/managed-chrome-9223

Use that dedicated profile for automation instead of attaching to a human Chrome profile.

Validation

Minimum same-machine checks:

npm run check
npm run encoding:check
npm run managed:chrome:start
npm run managed:playwright:smoke
npm run desktop:health
npm run desktop:unicode-smoke
node --check src/dynamic-control-mcp.mjs

For end-to-end lane testing, open:

input/unified-automation-harness/index.html

That harness exercises browser DOM work, native file-picker handoff, prompt rescue, and browser-aware dynamic-surface escalation.

Repository Map

• src/browser-control-mcp.mjs - optional persistent Playwright browser MCP
• src/windows-desktop-mcp.mjs - Windows desktop MCP bridge
• src/dynamic-control-mcp.mjs - dynamic-control MCP bridge
• scripts/start-managed-chrome.ps1 - launches the dedicated Chrome CDP endpoint
• scripts/invoke-managed-chrome-playwright.ps1 - runs Playwright scripts against the managed Chrome endpoint
• scripts/desktop-control.ps1 - direct PowerShell wrapper for desktop control
• scripts/dynamic_surface_browser_pipeline.py - browser-aware dynamic target loop
• docs/UNIVERSAL_COMPUTER_AUTOMATION.md - routing model and lane contract
• docs/BROWSER_FAILSAFE_MODE.md - managed browser and failsafe rules
• docs/WINDOWS_DESKTOP_CONTROL.md - desktop bridge behavior
• docs/GAME_AUTOMATION.md - dynamic-control runtime

Core Capabilities

Helix Control provides reusable building blocks for:

• browser automation
• native desktop control
• dynamic visual control
• bounded diagnostics and rescue helpers

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: miyahluvgames-source
• Source: miyahluvgames-source/helix-computer-use
• License: MIT

Install and usage instructions live in the source repository linked above.