cmo-agent-bridge

# CMO Agent Bridge Let Codex, Claude Code, Cursor and other Agents directly read and operate the running **Command: Modern Operations (CMO)** scenario. [](https://github.com/Nuclear2/cmo-agent-bridge/actions/workflows/ci.yml) [](docs/installation.md) [](https://github.com/Nuclear2/cmo-agent-bridge/releases) [](LICENSE) > **Platform Support: Windows only.** [Download v0.2.1](https://github.com/Nuclear2/cmo-agent-bridge/releases/tag/v0.2.1) · [Quick Start](docs/quickstart.md) · [Install for each framework](docs/frameworks/README.md) · [CMO Lua API](https://commandlua.github.io/) CMO Agent Bridge organizes 76 structured MCP tools from CMO's Lua API. Agents can read the battlefield situation, create tasks, allocate forces, plan routes and refueling, and assist in making units, weather, and events. All communication stays on the local machine, and the CMO side only needs to run a short polling event. After entering a scenario, the Agent will first read the scenario introduction and the current player's briefing, confirm the campaign goal, known intelligence, ROE, time limit, and victory criteria, and then start situation assessment and deployment; briefings of other camps will not be read. > **Current version is v0.2.1 Preview.** Verified on Windows and CMO Build 1868; it's recommended to use a scenario copy for the first connection. ## You can directly say > Connect to the current scenario in `LIVE_PLAYER` mode. Summarize our air situation and known threats, and then provide CAP adjustment suggestions. Do not modify the scenario for now. > Create a new task area between the two existing CAP areas, assign all J-36s to it, and then read back the task and allocation results. > In `SCENARIO_AUTHOR` mode, add an entry area trigger event for this scenario and check if the trigger, condition, and action are correctly associated. It suits three types of work: | Scenario | Work that can be done | |---|---| | Wargaming | Situation assessment, task planning, force allocation, orders and WRA, EMCON, routes, refueling, engagement, and time multiplier | | Scenario making | Factions, units, tasks, weather, timeline, events, Special Action, scoring, and partial inventory settings | | Testing and judging | Controlled injection, scenario checking, fault diagnosis, and judging records | ## Quick Start (Windows) The following example uses the Steam default installation path and PowerShell. ### 1. Install uv The bridge is managed by [`uv`](https://docs.astral.sh/uv/getting-started/installation/). Run in PowerShell: ```powershell winget install --id astral-sh.uv -e uv --version ``` `uv 0.11.26` or higher is required; if already installed but the version is older, run `winget upgrade --id astral-sh.uv -e`. `uvx` will prepare an independent Python 3.12 environment and running dependencies for the bridge. ### 2. Install Agent plugin #### Only for ChatGPT / Codex Desktop If there is no available `codex` CLI, download and run the Desktop installation script: ```powershell $installer = Join-Path $env:TEMP "install-codex-desktop.ps1" Invoke-WebRequest ` -UseBasicParsing ` -Uri "https://github.com/Nuclear2/cmo-agent-bridge/releases/download/v0.2.1/install-codex-desktop.ps1" ` -OutFile $installer powershell.exe -NoProfile -ExecutionPolicy Bypass -File $installer ``` The script will add the local plugin source to **Plugins → Personal**, and no Codex CLI is needed. Completely exit and restart Desktop, then open `cmo-agent-bridge` in **Personal** and click Install. The plugin still needs `uv` / `uvx` installed in step 1 to run MCP. #### For Codex CLI ```powershell codex plugin marketplace add Nuclear2/cmo-agent-bridge --ref stable codex plugin add cmo-agent-bridge@cmo-tools ``` The second command can also be replaced by opening `/plugins` in Codex and installing `cmo-agent-bridge` from **CMO Tools**. The remote self-built marketplace will not automatically appear in the official plugin directory, and the first command must be executed first. `stable` will only be promoted after the Release is complete; Codex will automatically check for updates when started, or you can run `codex plugin marketplace upgrade cmo-tools` to refresh immediately. #### For Claude Code ```powershell claude plugin marketplace add Nuclear2/cmo-agent-bridge@stable claude plugin install cmo-agent-bridge@cmo-tools --scope user ``` Claude Code's third-party marketplace auto-update is disabled by default. After installation, you can enable auto-update in `/plugin` → **Marketplaces** → `cmo-tools`; or manually run `claude plugin update cmo-agent-bridge@cmo-tools --scope user`. Execute `/reload-plugins` or create a new session to load. Both Codex and Claude plugins contain MCP configuration and complete `operate-cmo` Skill. See [Install for each framework](docs/frameworks/README.md) for OpenCode, Cursor, Qoder, and general MCP client configuration. These frameworks must register the local `stdio` MCP Server and install the complete `operate-cmo` Skill; the MCP protocol itself does not carry Skill. ### 3. Deploy CMO side runtime Restart the Agent and create a new task, then directly tell it: > Call `cmo_bridge_diagnose` to check the current installation; if it's not ready, use `D:\Program Files (x86)\Steam\steamapps\common\Command - Modern Operations` as `game_root` to call `cmo_bridge_prepare`. `cmo_bridge_prepare` will deploy the Lua runtime matching the plugin version and make the common tools in the current MCP session available immediately, without needing to restart again. If CMO is installed in another location, replace the path in the prompt with the actual path. The CLI is only used as a backup entry for [installation and troubleshooting](docs/installation.md). The plugin still uses the same version wheel: ```powershell $wheel = "https://github.com/Nuclear2/cmo-agent-bridge/releases/download/v0.2.1/cmo_agent_bridge-0.2.1-py3-none-any.whl" ``` When upgrading an existing installation, first confirm `queued=0` and `active=0` in `cmo_queue_status` with the old/current version, and let the worker complete the pending journal convergence, then upgrade the plugin/wheel and run `prepare`. The new `prepare` will check again before rewriting the Lua runtime; if it returns `STATE_CONFLICT`, do not manually delete the journal, go back to the version that produced the state and complete the recovery. See [Upgrade threshold](docs/installation.md#upgrade-with-prepare-safety-threshold) for details. ### 4. Save polling event in the scenario This step is done by the scenario author once. Open the scenario editor and create a new enabled and repeatable event: 1. Add a **Regular Time** trigger with an interval of 1 second; 2. Add a **Lua Script** action with the content: ```lua return ScenEdit_RunScript('CMOAgentBridge/inbox/request.lua') ``` 3. Associate the trigger and action with the event, then save the scenario. The event will be saved with the scenario, and the bridge can be used directly in normal wargaming mode. The Regular Time will process requests when the scenario time flows; when synchronous reading, initial state handshake, or immediate execution queue is required, adjust the time multiplier to 1x, and restore it after verification. ### 5. Confirm connection Keep CMO and the target scenario running, and tell the Agent: > Call `cmo_bridge_status` and tell me the current CMO build, runtime tag, and scenario lineage. If the result is successful, it means the CMO side is connected. If synchronous reading or state requests keep waiting, check if the polling event is enabled, allows repetition, and if the scenario time is flowing. If the `cmo_*` tools do not appear in the Agent, check the plugin and `uvx` and restart the Agent and create a new task. ## Write operation and pause v0.2.0 will persist ordinary write operations to the local FIFO queue, and the tool returns `QueuedOperationReceipt` immediately. Use the `request_id` in the receipt to call `cmo_request_get` or `cmo_request_wait` to get the final result; `cmo_request_wait` will not cancel the request if it times out. When CMO is paused, the submitted write operations will be retained, and executed in the order of submission after the time flow is restored. At this time, you can still use `cmo_request_get`, `cmo_request_list`, `cmo_queue_status` on the local machine, and cancel the `queued` requests that have not entered the execution stage with `cmo_request_cancel`. The `active` requests cannot be revoked, and closing the Agent or MCP will not cancel it; the next startup will continue to verify and recover. If the CMO process or scenario has changed, the bridge will reject or isolate old requests and not bring them to the new scenario. Independent modifications can be submitted continuously, and the queue will maintain the order. When the next step requires the GUID returned by the previous step (e.g., creating a task first, then allocating units), you must wait for the creation request to `completed` and get the GUID from the result. Reading tools still depend on CMO polling synchronously; when paused, they may return with the original timeout, so use `cmo_bridge_status` to establish and confirm the current session binding first. ## Wargaming, scenario making, and testing The Skill will use different information ranges according to the work content: | Mode | Information range | Applicable work | |---|---|---| | `LIVE_PLAYER` | Our situation and contacts observed by us | Normal wargaming, deployment, engagement, and support | | `SCENARIO_AUTHOR` | Complete scenario state | Making or modifying scenarios, events, forces, and scoring | | `UMPIRE` | Complete state within the approved judging range | Testing, injection, diagnosis, and judging | Use `LIVE_PLAYER` in daily wargaming; when making scenarios or testing and judging, switch to the corresponding mode. This allows the Agent to make full use of the editor's capabilities while retaining the intelligence uncertainty in normal wargaming. ## Working principle ```text Agent ── stdio / MCP ──> cmo-bridge ── local file bridge ──> CMO Lua event ``` - **MCP Server** provides 76 `cmo_*` tools, responsible for host preparation, diagnosis, persistent write queue, and reading and modifying CMO state; - **operate-cmo Skill** provides situation assessment, operational planning, execution inspection, and scenario making process; - **CLI** is used for installing runtime, diagnosing connection, and manual testing; `submit` only persists requests, and `request-wait` will start a foreground worker if there is no MCP server; - **Plugin** packages MCP configuration and Skill for Codex and Claude Code, and other frameworks can directly register the standard `stdio` MCP Server. The bridge runs as a local `stdio` process. The Agent, Python process, and CMO Lua runtime exchange requests and results through local file exchange; the local SQLite saves the session binding and persistent FIFO write queue, supporting pause waiting and restart recovery. ## Documentation - [Quick Start](docs/quickstart.md) - [Installation, upgrade, and uninstallation](docs/installation.md) - [Configuration for each Agent framework](docs/frameworks/README.md) - [Change log](CHANGELOG.md) - [Security instructions](SECURITY.md) - [Contribute](CONTRIBUTING.md) - [CMO official Lua API](https://commandlua.github.io/) ## Project status - Current version: [`v0.2.1 Preview`](https://github.com/Nuclear2/cmo-agent-bridge/releases/tag/v0.2.1) - Verified environment: Windows 10/11, CMO Build 1868 - Python: 3.12, isolated and managed by `uv` - License: [MIT](LICENSE) This is an unofficial community project, not affiliated with WarfareSims, Matrix Games, Slitherine, or CMO developers, publishers. The Agent's operation will directly modify the current scenario; please save a copy before using it for the first time; see [Security instructions](SECURITY.md) for detailed precautions. The CMO icon in the plugin and Skill is from the game's `Command.ico`; related rights belong to the original rights holders and are not covered by this project's MIT license.