cmdr-mcp 0.3.0 → 0.4.0

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
     {
       "name": "cmdr",
       "source": "./plugins/cmdr",
-      "version": "0.3.0",
+      "version": "0.4.0",
       "description": "Local multi-agent squads with durable messages, roles and lifecycle reminders."
     }
   ],

package/README.md

@@ -8,7 +8,23 @@
 
 Requires macOS or Linux and **Node.js ≥22.5** (24 recommended). The development branch contains source and plugin metadata. npm packages and the generated `marketplace` branch include the runtime bundles.
 
-The npm package is **`cmdr-mcp`**; the CLI and host plugin remain **`cmdr`**. Install with:
+**One-command setup (0.4.0):** replace `claude-code` with `codex` or `zcode` for your host.
+
+```sh
+npx -y --package=cmdr-mcp@latest cmdr setup --agent claude-code
+```
+
+Setup installs the runtime, skill, MCP and hooks while preserving existing settings. Repeat to upgrade; add `--dry-run` to preview. Open a new session and complete any host trust prompts. For a built checkout, use `plugins/cmdr/bin/cmdr setup --agent …`.
+
+For skill files only:
+
+```sh
+npx skills add njugray/cmdr --skill cmdr
+```
+
+The skill requires a working cmdr runtime and MCP connection. Use setup or the native plugin below for those components. See [installation details](docs/setup.md).
+
+The npm package is **`cmdr-mcp`**; the CLI and host plugin remain **`cmdr`**. For a global CLI and native plugin installation:
 
 ```sh
 npm install --global cmdr-mcp
@@ -26,7 +42,7 @@ For distribution, `npm pack` (or `npm publish`) runs `prepack` to build the four
 
 ```sh
 npm pack
-npm install --global ./cmdr-mcp-0.2.0.tgz
+npm install --global ./cmdr-mcp-0.4.0.tgz
 cmdr --help
 ```
 

package/docs/README.zh-CN.md

@@ -8,7 +8,23 @@
 
 支持 macOS / Linux，需要 Node.js ≥22.5（推荐 24）。开发分支保存源码和插件元数据；npm 发布包及自动生成的 `marketplace` 分支包含完整运行时。
 
-npm 包名为 **`cmdr-mcp`**，CLI 和宿主插件仍叫 **`cmdr`**。可直接安装：
+**一条命令完整安装（0.4.0）**，将 `claude-code` 换成实际使用的 `codex` 或 `zcode`：
+
+```sh
+npx -y --package=cmdr-mcp@latest cmdr setup --agent claude-code
+```
+
+安装器会安装运行时、技能、MCP 和 hooks，并保留已有配置。重复执行可升级，增加 `--dry-run` 可预览。完成后新开会话并处理宿主信任提示。构建后的源码可直接运行 `plugins/cmdr/bin/cmdr setup --agent …`。
+
+只安装技能文件时使用：
+
+```sh
+npx skills add njugray/cmdr --skill cmdr
+```
+
+技能需要可用的 cmdr 运行时和 MCP 连接，可通过 setup 或下面的原生插件方式安装。配置位置、升级和恢复见[安装说明](setup.md)。
+
+npm 包名为 **`cmdr-mcp`**，CLI 和宿主插件仍叫 **`cmdr`**。需要全局 CLI 或原生插件时也可安装：
 
 ```sh
 npm install --global cmdr-mcp
@@ -26,7 +42,7 @@ npm run build
 
 ```sh
 npm pack
-npm install --global ./cmdr-mcp-0.2.0.tgz
+npm install --global ./cmdr-mcp-0.4.0.tgz
 cmdr --help
 ```
 

package/docs/agent-integration.md

@@ -4,6 +4,8 @@ Build a source checkout with `npm ci && npm run build`, or use the unpacked/inst
 
 The daemon and message model accept arbitrary lowercase Agent IDs (`[a-z][a-z0-9_-]{0,63}`), not a closed Claude/Codex enum. All hosts share the same seven MCP tools. Specialized adapters add identity, working-directory discovery and lifecycle reminders; none is required to use the queue.
 
+For automatic runtime, skill and user MCP/hooks installation, use [standalone setup](setup.md). The manual and native-plugin contracts follow below.
+
 ## Other MCP hosts
 
 ```sh

package/docs/implementation.md

@@ -1,6 +1,6 @@
 # Implementation and verification
 
-This document records the implementation and its verification scope. The design's historical v0.1.x trial reports described a prior prototype; they are not test evidence for this implementation. This release is versioned from `package.json` as **0.3.0**, internal protocol **1**.
+This document records the implementation and its verification scope. The design's historical v0.1.x trial reports described a prior prototype; they are not test evidence for this implementation. This release is versioned from `package.json` as **0.4.0**, internal protocol **1**.
 
 ## Delivered behavior
 
@@ -83,6 +83,12 @@ The Codex adapter uses the installed CLI's generated public request/response typ
 
 Local verification for 0.2.0 (2026-09-16): `npm run check` passed 79 tests plus offline npm installation and seven-tool discovery; the targeted Node 22.5.0 suite passed 44 tests, including preflight and managed daemon processes. `npm run verify:zcode` validated the native plugin, discovered 1 command / 3 skills / 4 hooks / 1 MCP server, and connected seven tools from a fresh cache after removing the source directory. No model request was made.
 
+## Standalone setup
+
+`cmdr setup` copies a verified runtime to a persistent build directory and installs profile-specific launchers, the `cmdr` skill and user MCP/hooks. Configuration edits preserve unrelated values and support backup/rollback. See [setup](setup.md) for usage and recovery.
+
+The standalone skill owns the role references; the build synchronizes the existing role skill entries from them. Setup tests cover all three hosts, upgrades, configuration preservation, failure recovery and profile isolation. Package verification runs the real npx entry point offline and checks it after removing the npx cache. Host GUI trust and live-model collaboration require separate verification.
+
 A read-only probe of the installed Codex CLI 0.153.4 confirmed that this desktop environment does not expose the CLI's default shared control socket. Live-model wake execution therefore remains unverified here; tests use a deterministic public-protocol host fixture. The adapter reports this transport failure and supports an explicit host-provided socket rather than spawning a competing app-server.
 
 

package/docs/publishing.md

@@ -1,6 +1,6 @@
 # npm 发布
 
-本次发布版本为 `cmdr-mcp@0.3.0`。npm 包名是 `cmdr-mcp`，CLI、宿主插件和 marketplace 名称仍为 `cmdr`。安装后的包根目录是 `$(npm root -g)/cmdr-mcp`。
+本次发布版本为 `cmdr-mcp@0.4.0`。npm 包名是 `cmdr-mcp`，CLI、宿主插件和 marketplace 名称仍为 `cmdr`。全局安装后的包根目录是 `$(npm root -g)/cmdr-mcp`。
 
 ## 准备与验证
 
@@ -10,12 +10,12 @@
 npm ci
 npm run check
 npm pack
-npm publish ./cmdr-mcp-0.3.0.tgz --dry-run --access public --registry https://registry.npmjs.org/
+npm publish ./cmdr-mcp-0.4.0.tgz --dry-run --access public --registry https://registry.npmjs.org/
 ```
 
 涉及 ZCode 的发布另运行 `npm run verify:zcode`：从实际 tarball 安装到隔离缓存，核对完整性并移走安装源后验证 7 个工具；需要本机 ZCode runtime。
 
-`npm run check` 包括格式、类型、构建、测试以及临时目录中的 npm 包离线安装验证：检查发布资源、安装后 marketplace 路径、CLI 和 7 个 MCP 工具。`npm pack` 通过 `prepack` 生成 4 个运行入口及第三方许可证声明，输出 `cmdr-mcp-0.3.0.tgz`。源码、测试和开发依赖不进入发布包。
+`npm run check` 包括格式、类型、构建、测试以及临时目录中的 npm 包离线安装验证：检查发布资源、安装后 marketplace 路径、CLI 和 7 个 MCP 工具。`npm pack` 通过 `prepack` 生成 4 个运行入口及第三方许可证声明，输出 `cmdr-mcp-0.4.0.tgz`。源码、测试和开发依赖不进入发布包。
 
 检查 `git diff`，确认版本与预期一致，构建未意外修改宿主 manifests。发布前保留经过验证的源码提交；不要手改或提交 `plugins/cmdr/dist/`、`THIRD_PARTY_NOTICES.txt` 和 `.tgz`。
 
@@ -36,20 +36,20 @@ npm view cmdr-mcp name version --registry https://registry.npmjs.org/
 确认发布时，上传已检查的 tarball，并按 npm 提示完成账号验证：
 
 ```sh
-npm publish ./cmdr-mcp-0.3.0.tgz --access public --registry https://registry.npmjs.org/
+npm publish ./cmdr-mcp-0.4.0.tgz --access public --registry https://registry.npmjs.org/
 ```
 
-此命令会公开发布 `0.3.0` 并使用默认的 `latest` 标签。相同包名和版本不能重复发布；后续修改需要提升版本并重新构建验证。发布使用 tarball，以保持上传内容与已检查产物一致。
+此命令会公开发布 `0.4.0` 并使用默认的 `latest` 标签。相同包名和版本不能重复发布；后续修改需要提升版本并重新构建验证。发布使用 tarball，以保持上传内容与已检查产物一致。
 
 ## 发布后核对
 
 ```sh
-npm view cmdr-mcp@0.3.0 name version dist.integrity --registry https://registry.npmjs.org/
-npm install --global cmdr-mcp@0.3.0 --registry https://registry.npmjs.org/
+npm view cmdr-mcp@0.4.0 name version dist.integrity --registry https://registry.npmjs.org/
+npm install --global cmdr-mcp@0.4.0 --registry https://registry.npmjs.org/
 cmdr --help
 ```
 
-按照 [安装说明](README.zh-CN.md#安装) 注册安装后的包根目录。升级后刷新或重装宿主插件缓存，重启 MCP 连接，并使用新版本 CLI 执行 `cmdr daemon restart`；该命令先做一致性预检，再替换旧 daemon。随后重新检查监听状态，Claude/ZCode 按 `listener.arm` 重新挂载 watcher。不要仅替换 npm 包后继续使用旧缓存和旧 daemon。
+按照[安装说明](README.zh-CN.md#安装)运行 setup 或注册原生插件。原生插件升级后刷新或重装宿主缓存，使用新版本 CLI 执行 `cmdr daemon restart`，再重连 MCP；该命令先做一致性预检，再替换旧 daemon。随后检查监听状态，Claude/ZCode 按 `listener.arm` 重新挂载 watcher。
 
 npm 命令行为参考：[npm publish 官方文档](https://docs.npmjs.com/cli/v11/commands/npm-publish/)。
 

package/docs/setup.md

@@ -0,0 +1,45 @@
+# Standalone setup
+
+Available from cmdr-mcp 0.4.0. Requires macOS/Linux and Node.js >=22.5 (24 recommended).
+
+```sh
+npx -y --package=cmdr-mcp@latest cmdr setup --agent claude-code
+```
+
+Choose `claude-code`, `codex` or `zcode`. Setup installs a persistent runtime, the `cmdr` skill, MCP and user hooks, then checks the seven tools in temporary state. Use the printed CLI path (normally `~/.cmdr/bin/cmdr`), open a new host session and complete any trust prompts. Existing hook opt-outs are preserved. Other MCP hosts use `cmdr config --agent <host-id>`.
+
+To install only the self-contained skill and its role/setup references:
+
+```sh
+npx skills add njugray/cmdr --skill cmdr
+```
+
+Add `-g` for global scope or `--agent <supported-agent>` to select a host. This installs no runtime or MCP configuration; use an existing cmdr integration or run setup. Choose setup or the native plugin for each host to avoid duplicate tools and hooks. Invoke the standalone skill through the host's skill interface or ask “use cmdr to join my-project”.
+
+## Configuration
+
+| Host | MCP configuration | User hooks | Skill |
+| --- | --- | --- | --- |
+| Claude Code (`claude-code`, alias `claude`) | `~/.claude.json` | `~/.claude/settings.json` | `~/.claude/skills/cmdr` |
+| Codex | `$CODEX_HOME/config.toml`, default `~/.codex/config.toml` | `$CODEX_HOME/hooks.json` | `$CODEX_HOME/skills/cmdr` |
+| ZCode | `~/.zcode/cli/config.json`, `mcp.servers` | Same file, `hooks.events` | `~/.zcode/skills/cmdr` |
+
+| Option | Purpose |
+| --- | --- |
+| `--dry-run` | Preview destinations/conflicts without installing runtime or changing host configuration |
+| `--json` | Return paths, changes, warnings and backup location as JSON |
+| `--config-dir PATH` | Select a custom host **user** profile directory; launch the host with that same profile |
+
+`CLAUDE_CONFIG_DIR` is respected; its MCP file is `<CLAUDE_CONFIG_DIR>/.claude.json`. ZCode loads user hooks, not workspace hooks. `CMDR_HOME` selects runtime/state storage (default `~/.cmdr`): build directories live in `runtimes/`, stable profile-specific launchers in `bin/`. They survive npx cache removal and bind the host/state directory, never a fixed session ID. See [host integration](agent-integration.md) for identity and lifecycle contracts.
+
+## Upgrade and recovery
+
+Repeat setup with the newer package to upgrade. Unchanged files stay unchanged; prior runtime directories remain available to existing processes. Setup does not restart the daemon. If it reports `UPGRADE_REQUIRED`, coordinate active work, run `<printed-cli> daemon restart`, then reconnect sessions.
+
+Setup preserves other servers, settings and hooks. Codex retains unrelated TOML text/comments; JSON settings are reformatted without discarding other values. Malformed configuration, an enabled cmdr plugin, an unmanaged cmdr MCP entry or an unrelated skill named `cmdr` stops setup before host changes.
+
+Existing copies/symlinks of this repository's skill are backed up and replaced with a link to the persistent runtime. Shared npx-skills sources are left intact; custom files in an adopted copy remain in its backup. Upgrade setup-managed skills through setup.
+
+Backups live in `<CMDR_HOME>/setup-backups/<run>/`. `restore.json` maps each changed path to its backup (`null` marks a newly created entry). Failed writes are rolled back; concurrent edits are reported for manual recovery. After a crash, inspect that record before retrying. Remove a stale `setup.lock` only after confirming its recorded process has stopped.
+
+For diagnostics, run `<printed-cli> doctor --deep`. Move a damaged runtime directory aside and rerun setup from an intact package. Native plugins require their own cache refresh. For [automatic standby](long-running-collaboration.md#automatic-standby), Claude/ZCode arm `listener.arm.command` with the indicated native host tool; Codex uses daemon-managed proxy/queue delivery. GUI trust, actual hook execution and automatic wake must be verified in the host; setup's isolated MCP check does not establish those capabilities.

package/marketplace.json

@@ -4,7 +4,7 @@
     {
       "name": "cmdr",
       "source": "./plugins/cmdr",
-      "version": "0.3.0",
+      "version": "0.4.0",
       "description": "Local multi-agent squads with durable messages, roles and lifecycle reminders."
     }
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cmdr-mcp",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "description": "Local multi-agent squads for Claude Code, Codex, ZCode and any MCP host",
   "engines": {
@@ -19,12 +19,13 @@
     "verify:package": "node scripts/verify-package.mjs"
   },
   "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "@types/node": "^24.0.0",
     "esbuild": "^0.25.0",
     "prettier": "^3.9.6",
+    "smol-toml": "^1.8.0",
     "typescript": "^5.9.0",
     "vitest": "^3.2.0",
-    "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^3.25.0"
   },
   "files": [

package/plugins/cmdr/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cmdr",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Local multi-agent squads with durable messages, roles and lifecycle reminders.",
   "author": {
     "name": "njugray"

package/plugins/cmdr/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cmdr",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Local multi-agent squads with durable messages, roles and lifecycle reminders.",
   "author": {
     "name": "njugray"

package/plugins/cmdr/.zcode-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "cmdr",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Local multi-agent squads with durable messages, roles and lifecycle reminders.",
   "author": {
     "name": "njugray"

package/plugins/cmdr/README.md

@@ -2,6 +2,8 @@
 
 Connect local Claude Code, Codex, ZCode and other MCP-capable sessions as a squad. Requires macOS/Linux and Node.js ≥22.5 (24 recommended); npm distribution packages include all runtime dependencies. A source checkout requires `npm ci && npm run build` at the repository root before installation; generated `dist` files are not tracked by Git.
 
+For installation through `cmdr setup` or `npx skills`, see [standalone setup](https://github.com/njugray/cmdr/blob/main/docs/setup.md). Use one installation method per host to avoid duplicate tools and hooks.
+
 In each session enter `/cmdr my-project`. Joining defaults to executor, even for a new channel. Explicitly use role="commander" to claim command; no commander is required to retain a channel. Without slash commands, ask the Agent to call `join(squad_name="my-project")`.
 
 Tools: `join`, `list`, `send`, `report`, `ask`, `read`, `leave`. Executors report ready with capabilities/cwd, then read tasks, report results and ask when blocked. Commanders dispatch verifiable tasks and answer questions with `reply_to`. Acknowledge each command with working + reply_to before executing it. Use read(recover=true) to find unfinished commands after interruptions. Offline never means stopped. Use join(standby="auto") and check listener health; with a healthy listener, end the idle turn. Manual fallback is limited to two recommended waits.

package/plugins/cmdr/THIRD_PARTY_NOTICES.txt

@@ -161,6 +161,35 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
 
+========================================================================
+
+smol-toml 1.8.0 (BSD-3-Clause)
+Copyright (c) Squirrel Chat et al., All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software without
+   specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
 ========================================================================
 
 zod 3.25.76 (MIT)

package/plugins/cmdr/commands/cmdr.md

@@ -4,4 +4,4 @@ argument-hint: <name>
 ---
 Call join(squad_name="$ARGUMENTS", standby="auto") for atomic find-or-create. If no name was provided, ask for one; do not invent it. Joining defaults to executor, including a channel without a commander. Add role="commander" if the user explicitly requested command; use takeover=true only for requested handover.
 Follow protocol_hint and the role skill. Executors report ready with cwd and capabilities. Give a brief translated user_reply preserving the join line. For Claude/ZCode, arm listener.arm.command with the indicated native host tool, following the role skill; re-arm on task termination or restart. Check listener health and end the idle turn when can_auto_respond=true. Use at most two recommended waits only when native wake is unavailable; explain the actual limitation.
-If tools are unavailable, follow using-cmdr diagnostics and member CLI fallback. Use the real host session ID, never an invented identity or raw socket workaround.
+If tools are unavailable, follow the cmdr skill's setup reference (or using-cmdr diagnostics for legacy installs) and member CLI fallback. Use the real host session ID, never an invented identity or raw socket workaround.