# AutoHano Works — AI-readable install and connection guide

This is an English translation of the Korean ai-install.md.

This document is the procedure an AI tool running on a person's PC (Claude Code, Codex CLI, etc.) follows to install AutoHano Works and connect it as one of its own tools. Steps a human must do are marked **[Human]**. Windows 10/11 (64-bit) only.

## 0. What you need

- Basic features (history · compare · Find address · ladder view · reports · Connect AI): a Windows 10/11 64-bit PC, internet access, and a Google, Kakao or Naver account. No separate runtime to install and no administrator rights are needed (Works listens only on `127.0.0.1`). It also works on a PC without XG5000.
- .xgwx generation (local engine, section 4): XG5000 — if it is installed on this PC, it is copied and used as is; if not, it is installed from the XG5000 installer on the LS ELECTRIC website. 8 GB of free disk space. On a new PC, the first time may need **[Human]** administrator approval and a restart. Opening a generated file right away with `open=true` uses the XG5000 on this PC.
- Company PC: if security software blocks an unfamiliar exe, or if `works.autohano.com` (sign-in) or the places downloaded from during engine installation are blocked, **[Human]** ask the IT team to allow them. Blocked addresses are shown in `hint` of `GET /api/engine/status`.

## What Works is

A version history, comparison and address search tool for LS ELECTRIC PLC files (XG5000 .xgwx, XP-Builder .xpd), and a generation engine that returns a program written by AI as an .xgwx that a real XG5000 has built into a project and checked (35 CPU types: XGI·XGR ST, XGB (IEC) IL, XGK·XGB ladder). The installed version keeps the original files on the PC, but the source and analysis results you request are passed to the connected AI. The remote MCP goes through the account server. It is not official LS ELECTRIC software.

## 1. Download [Human]

1. Open https://works.autohano.com/download in a browser and sign in with a Google, Kakao or Naver account; `AutoHanoWorks.zip` downloads. There is no way to download it without signing in.
2. Extract the zip into any folder (e.g. `C:\AutoHano`) and tell the AI the folder path.

## 2. Run (the AI may do this)

- Run `AutoHanoWorks.exe` in the folder. It is not an installer — running it is the installation; it stays in the tray and a small window (the launcher) opens. If Windows SmartScreen shows "Windows protected your PC" the first time, **[Human]** [More info] → [Run anyway].
- The Works screen is at `http://127.0.0.1:4011` (or the port set with the environment variable `WORKBENCH_PORT`, if changed). [Open Works] in the tray icon menu also opens it. To check that it is running: `GET /api/health`.
- On first start, the Sign in section of the small window is expanded. **[Human]** Click Google, Kakao or Naver and sign in in the browser, then click [Open Works] and agree to the terms. An account is used on only one PC at a time.

## 3. Connect to the AI tool

There are two ways, with the same tool list. On the user's PC, **[Connect AI] in the launcher window** (it opens when the exe is run) connects Works to Claude Desktop · Claude Code · Cursor · Codex on this PC with one button — below is the guide for when the AI sets it up itself.

**A. Internet connector (Claude web · app, ChatGPT, Claude Code from anywhere)** — one address: `https://works.autohano.com/mcp`
- Claude Code (on another PC): run `claude mcp add --transport http autohano-works https://works.autohano.com/mcp`, then on the sign-in page that opens on first use, **[Human]** sign in with the same account as Works. For Claude Code · Codex on the same PC as Works, B below is the default.
- Claude (web · app) · ChatGPT: **[Human]** Settings → Connectors → Add custom connector → the address above → sign in. It is often available only on each company's paid plans.
- The tools are run by Works on this PC. If Works is off, the tools return a "turn on Works" message.

**B. Directly on this PC (no server; Claude Code · Codex · Cursor) — on the same PC this is faster and has no sign-in window**

`<extracted folder>` is the folder of the Works that is running now — where the `command` (…\runtime\node.exe) of `GET http://127.0.0.1:4011/api/mcp/info` is.
1. Check: `claude mcp get autohano-workbench` · `codex mcp get autohano-workbench`. If Command is `<extracted folder>\runtime\node.exe`, it is already connected ("Connected" alone does not tell you whether it is the right folder — look at the path).
2. If it points to another folder, remove it: `claude mcp remove autohano-workbench -s user` · `codex mcp remove autohano-workbench`.
3. Add it:
   - Claude Code: `claude mcp add autohano-workbench -s user -e WORKBENCH_API=http://127.0.0.1:4011 -- "<extracted folder>\runtime\node.exe" "<extracted folder>\app\mcp.mjs"`
   - Codex: `codex mcp add autohano-workbench --env WORKBENCH_API=http://127.0.0.1:4011 -- "<extracted folder>\runtime\node.exe" "<extracted folder>\app\mcp.mjs"`
   - The same commands with this PC's paths filled in: `snippets.claude` · `snippets.codexCli` of `/api/mcp/info`, the [Copy] buttons in [Settings → Connect AI] on the Works screen, and `CLAUDE.md` · `AGENTS.md` in the extracted folder.
4. The tools appear only after the AI tool is restarted. Do not touch existing MCP servers with other names.

## 4. Unlimited plan feature: local engine (optional)

To generate .xgwx on this PC without limits, install the engine (trial · Unlimited plan). Use [Install the local engine → Install on this PC] in the small window, [Settings → Local engine → Install on this PC] on the Works screen, or the API `POST /api/engine/install`. The first time takes about 10 minutes, downloads about 1 GB and needs 8 GB of free disk space. Progress is in `GET /api/engine/status` — when `installing` becomes false, look at `phase`. If it stops, `hint` says in plain words what to do at that point.

| `phase` | What to do |
|---|---|
| `reboot` + `wsl: "missing"` | `POST /api/engine/wsl-install` — a Windows administrator approval window appears. **[Human]** click "Yes". When it finishes, **[Human]** restart the PC → run Works again → `POST /api/engine/install` |
| `reboot` (preparation done) | **[Human]** restart the PC → run Works again → `POST /api/engine/install` |
| `bios` | First **[Human]** restart, then `POST /api/engine/install`. If it is still `bios`, **[Human]** turn on virtualization (Intel VT-x / AMD SVM) in the BIOS — no program can do this for them |
| `need-xg5000` | **[Human]** download the XG5000 installer from the LS ELECTRIC website (an .exe whose name starts with `XG5000`, or the downloaded .zip as is). `POST /api/engine/installer` — header `x-file-name: <URL-encoded file name>`, body = the raw file bytes (e.g. `curl --data-binary @<file> -H "x-file-name: <name>" http://127.0.0.1:4011/api/engine/installer`) → `POST /api/engine/install` |
| `error` | Retry with `POST /api/engine/install` as `hint` says. If it stops at the same point again, show the human the `error` · `log` from the status, and contact support@autohano.com |
| `ready` + `ready: true` | Done. `generate_xgwx` · `edit_program` · `change_program` · `check_xgwx` run on this PC |

## 5. First things to try

Once connected, the AI first calls `workbench_status`.

- **"Analyze this file (folder)"**: `add_file(path=full path)` → with the returned versionId, `project_summary` (program names) → `list_variables` (variable/device table: comment · read/write · rungs where used) → `program_ladder` ("condition → output" per rung — OR branches and parallel outputs exactly as in the file; device comments in parentheses) · `st_source`. For HMI screens (.xpd), `screen_objects`.
- **"Check the servo (○○) sequence"**: find the signals and the rungs that use them with `list_variables(query="servo")` · `home` · `alarm` · `APM` · `XPM` etc. → read those rungs in order with `program_ladder(query=device)` and explain the sequence, conditions and interlocks. Mark anything not in the file as "needs verification".
- **"Organize the variables"**: all of `list_variables` + `only=unused` (unused) · `no-comment` (no comment) · `multi-write` (multiple writes — SET/RST pairs are counted too, so check in the rungs whether it is a double coil) · `io` (I/O). Give the cleanup plan as a suggestion; a person applies it in XG5000.
- **"Summarize the communication settings"**: `comm_settings` — online connection (PC→PLC) · CPU built-in Ethernet · Cnet channels (RS-485 · speed · station number · operation mode) · FEnet IP · Modbus server address table · P2P blocks (from where to where, like "0x40100 → D00100") · high-speed link. See at a glance what is exchanged with inverters, meters and HMIs.

Before generating, call `generate_profiles` (CPU list · input formats · rejection rules · examples). Generate with `generate_xgwx` (register=true adds it to the history right away; with compile=true it also confirms an actual compile and run on the simulator); to add it later, `register_xgwx` (job id). Example: "Build the pump station example as XGK-CPUA ladder and open it in XG5000" → `generate_profiles(sample=pump-station)` → `generate_xgwx(cpu=XGK-CPUA, program=…, open=true)`.

Editing an existing project (local engine): first look at what would change with `dryRun=true`, then edit for real (2–4 minutes per engine run).

- **Edit a program's text** with `edit_program`: for ST · IL, get the current text with `st_source` and pass the full edited text (`source`) or only the changes (`replace`). For ladder (XGK · XGB · XGI), edit rung by rung in `rungs` using the rung numbers of `program_ladder(format=il)` — replace `{rung, il}` · delete `{rung, remove}` · insert `{after, il}`. Add new variables with `variables`.
- **Add, rename or delete programs** with `change_program`. For several steps in a row, pass the previous job id as `fromJob` instead of `versionId` and `register=true` only on the last one — intermediate versions do not pile up in the history.
- **Check only** with `check_xgwx`: the XG5000 program check without editing (errors · warnings · double coil places).
- The "proof" in the result is Works comparing the edited file with the original (only the requested part changed; the other programs, variables and settings unchanged). When the proof passes and the check has 0 errors, `register=true` adds it as a new version of the same project.

## Principles

- Works never modifies the original file — an edit is made on a copy by XG5000 on this PC, checked, and added as a new version. A person checks the AI's conclusions, drafts and edited versions in XG5000 before anything goes onto real equipment.
- The local engine runs program generation, editing and checking on the PC. When requested through the remote MCP, the program input and results pass through the account server. When the generation server is used, the program input is sent to the server.
- Contact: support@autohano.com