windows98-mcp AGENTS.md

Windows 98 MCP and CLI operating rules

Target a named VM

• One broker listener can accept multiple Windows 98 guests. Configure a stable, case-insensitively unique name for each guest in WIN98CTL.INI:

  [connection]
  host=10.0.2.2
  port=9898
  name=win98-lab-a
  

• Use vm_list without a target to discover all known VM connections and their state. Include vm_name in every guest-targeted MCP tool input and in the params object of every JSON-lines RPC call, even when only one VM is connected. For CLI calls, pass --vm <name>.

• VM names compare case-insensitively. A duplicate live name is rejected with VM_NAME_IN_USE; the existing connection remains authoritative.

• Guest-targeted state and concurrency are per VM. Brokers in relay mode keep one upstream bridge per guest, so multiple named VMs can share both broker listeners and operate in parallel.

Choose an interface

• Prefer the win98 MCP tools when they are available.

• If only terminal/CLI access is available, use npx windows98-mcp tools to inspect every operation and its exact JSON schema, then use either:

  npx windows98-mcp call <method> --vm <name> --params '<JSON>'
  npx windows98-mcp rpc
  

• call is for one self-contained operation. It creates a temporary session and force-cleans it on exit. It intentionally rejects terminal operations, mouse_down, and keyboard-down operations; use rpc for those.

• rpc is a persistent JSON-lines session. Send one request per line as {"id":"unique-id","method":"method_name","params":{...}}; read matching JSON response lines. Keep it open for shell sessions, held input, input batches, and multi-step workflows. EOF force-cleans that RPC session.

• For a remote broker, add --broker-host <ip> --broker-port <port>. File and directory paths always belong to the machine running the CLI, not the remote broker host.

Connection, recovery, and concurrency

• The guest dials the host every two seconds. The MCP/CLI process stays usable when the VM is powered off. Guest tools return retryable VM_OFFLINE; retry after the guest reconnects without recreating the Codex task or CLI session.
• The adapter resumes short broker connection losses automatically and may replay interrupted work at least once. A replay can duplicate clicks, commands, or writes; inspect recovery.replayed in the result.
• Parallel operation is the default. The broker FIFO-serializes protocol calls independently per VM, so different named VMs can make progress at the same time. Mouse, keyboard, focus, clipboard, and screen state remain shared within each VM; coordinate interactive UI work targeting the same VM.
• vm_lock and vm_wait matter only when an operator enables exclusive lock agents. In that mode, use the returned FIFO ticket after VM_BUSY.
• For a managed QEMU VM, use host=10.0.2.2 in WIN98CTL.INI; it is QEMU's user-network host gateway. Do not use guest 127.0.0.1. The QEMU profile defaults include kernel-irqchip=off,hpet=off,usb=off and auto always has an emulation fallback.