nexo-brain 2.6.9 → 2.6.10

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "2.6.9",
+  "version": "2.6.10",
   "description": "Local cognitive runtime for Claude Code \u2014 persistent memory, overnight learning, doctor diagnostics, personal scripts, recovery-aware jobs, startup preflight, and optional dashboard/power helper.",
   "author": {
     "name": "NEXO Brain",

package/README.md

@@ -6,7 +6,7 @@
 [![GitHub stars](https://img.shields.io/github/stars/wazionapps/nexo?style=social)](https://github.com/wazionapps/nexo/stargazers)
 [![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](https://www.gnu.org/licenses/agpl-3.0)
 
-> Local cognitive runtime for Claude Code — persistent memory, overnight learning, runtime CLI, recovery-aware background jobs, startup preflight, and doctor diagnostics. 150+ MCP tools. Benchmarked on LoCoMo (F1 0.588, +55% vs GPT-4). Submitted to the Claude Code plugin marketplace.
+> Local cognitive runtime for Claude Code — persistent memory, overnight learning, runtime CLI, recovery-aware background jobs, startup preflight, and doctor diagnostics. 150+ MCP tools. Benchmarked on LoCoMo (F1 0.588, +55% vs GPT-4). Claude Code plugin packaging included.
 
 **NEXO Brain transforms any MCP-compatible AI agent from a stateless assistant into a cognitive partner that remembers, learns, forgets, adapts, and builds a relationship with you over time.**
 
@@ -536,7 +536,7 @@ Files and areas that cause repeated errors accumulate a risk score (0.0–1.0).
 npx nexo-brain
 ```
 
-The installer handles everything:
+The installer handles everything and syncs the same `nexo` MCP brain into Claude Code, Claude Desktop, and Codex when those clients are present:
 
 ```
   How should I call myself? (default: NEXO) > Atlas
@@ -570,6 +570,7 @@ After install, use the runtime CLI:
 nexo chat          # Launch Claude Code with NEXO as operator
 nexo doctor        # Check runtime health
 nexo update        # Pull latest version and sync
+nexo clients sync  # Re-sync Claude Code/Desktop/Codex to the same brain
 nexo scripts list  # See your personal scripts
 ```
 
@@ -583,7 +584,7 @@ Your operator will greet you immediately — adapted to the time of day, resumin
 |-----------|------|-------|
 | Cognitive engine | Python: fastembed, numpy, vector search | pip packages |
 | MCP server | 150+ tools for memory, cognition, learning, guard | NEXO_HOME/ |
-| Claude Code Plugin | Submitted to the Claude Code plugin marketplace (Anthropic) | `.claude-plugin/` |
+| Claude Code Plugin | Marketplace-ready (packaging verified) | `.claude-plugin/` |
 | Plugins | Guard, episodic memory, cognitive memory, entities, preferences, update, etc. | Code: src/plugins/, Personal: NEXO_HOME/plugins/ |
 | Hooks (7) | SessionStart, Stop, PostToolUse, PreCompact, PostCompact | NEXO_HOME/hooks/ |
 | Nervous system | 13 core recovery-aware jobs + optional helpers (dashboard, prevent-sleep) | NEXO_HOME/scripts/ |
@@ -596,6 +597,7 @@ Your operator will greet you immediately — adapted to the time of day, resumin
 | Schedule config | schedule.json with customizable process times and timezone | NEXO_HOME/config/ |
 | Auto-update | Non-blocking startup check (5s max), opt-out via schedule.json | Built into server startup |
 | CLAUDE.md tracker | Version-tracked core sections with safe updates preserving customizations | Built into auto-update |
+| Shared client sync | Same `nexo` MCP entry wired into Claude Code, Claude Desktop, and Codex | User config dirs |
 | Auto-diary | 3-layer system: PostToolUse every 10 calls, PreCompact emergency, heartbeat DIARY_OVERDUE | Built into hooks |
 | Claude Code config | MCP server + 7 hooks + 15 processes registered | ~/.claude/settings.json |
 
@@ -653,6 +655,7 @@ NEXO Brain separates **code** (immutable, in the repo or npm package) from **dat
 | `NEXO_HOME/data/` | SQLite databases (nexo.db, cognitive.db), migration state |
 
 The plugin loader scans `src/plugins/` first (base), then `NEXO_HOME/plugins/` (personal override by filename). This dual-directory approach lets you extend NEXO without forking the repo.
+The client sync layer points Claude Code, Claude Desktop, and Codex at the same runtime and `NEXO_HOME`, so all three clients share one brain instead of drifting into separate local memories.
 
 ### 150+ MCP Tools across 21+ Categories
 
@@ -743,6 +746,14 @@ npx nexo-brain
 
 All 150+ tools are available immediately after installation. The installer configures Claude Code's `~/.claude/settings.json` automatically.
 
+### Claude Desktop
+
+When Claude Desktop is installed, `nexo-brain`, `nexo update`, and `nexo clients sync` keep `claude_desktop_config.json` pointed at the same local NEXO runtime and `NEXO_HOME`.
+
+### Codex
+
+When Codex CLI is available, `nexo-brain`, `nexo update`, and `nexo clients sync` register the same `nexo` MCP server via `codex mcp add`, so Codex uses the same local memory store as Claude Code and Claude Desktop.
+
 ### OpenClaw
 
 NEXO Brain also works as a cognitive memory backend for [OpenClaw](https://github.com/openclaw/openclaw):
@@ -812,7 +823,7 @@ NEXO Brain works with any application that supports the MCP protocol. Configure
 | mcpservers.org | MCP Directory | [mcpservers.org](https://mcpservers.org) |
 | OpenClaw | Native Plugin | [openclaw.com](https://openclaw.ai) |
 | dev.to | Technical Article | [How I Applied Cognitive Psychology to AI Agents](https://dev.to/wazionapps/how-i-applied-cognitive-psychology-to-give-ai-agents-real-memory-2oce) |
-| Claude Code | Plugin (pending review) | Submitted to Anthropic's plugin marketplace |
+| Claude Code | Plugin (marketplace-ready) | Packaging verified, included in npm tarball |
 | nexo-brain.com | Official Website | [nexo-brain.com](https://nexo-brain.com) |
 
 ## Support the Project
@@ -828,6 +839,13 @@ If NEXO Brain is useful to you, consider:
 
 ## Changelog
 
+### v2.6.9 — Integration Sync, CI/CD Pipeline (2026-04-04)
+- **Release artifact sync**: Automated version synchronization across Claude Code plugin, OpenClaw package, and ClawHub skill before every publish.
+- **CI/CD pipeline**: Full GitHub Actions workflow for publish + verification of all integration channels.
+- **OpenClaw plugin hardened**: Contract tests, correct runtime path, synchronized version. Published as @wazionapps/openclaw-memory-nexo-brain@2.6.9.
+- **ClawHub skill hardened**: Version-synced metadata, correct server path, post-publish smoke verification.
+- **Claude Code plugin packaging**: Verified plugin.json, .mcp.json, hooks included in npm tarball. Marketplace-ready.
+
 ### v2.6.5 — Power Helper Hardening, Recovery Contracts (2026-04-04)
 - Power helper semantics explicit and safer: `always_on` = platform helper for best-effort background availability.
 - Catch-up recovery suppresses duplicate relaunches for in-flight `cron_runs`.
@@ -915,7 +933,7 @@ If NEXO Brain is useful to you, consider:
 - **HNSW Vector Index**: Optional approximate nearest neighbor acceleration (auto-activates above 10,000 memories)
 - **Claim Graph**: Decomposes blob memories into atomic verifiable facts with provenance and contradiction detection
 - **Inter-terminal Auto-inbox (D+)**: `nexo_startup` accepts `claude_session_id` for automatic inbox delivery between parallel terminals
-- **Tests**: 24 pytest tests across 3 suites (cognitive, knowledge graph, migrations)
+- **Tests**: 156 pytest tests across 3 suites (cognitive, knowledge graph, migrations)
 
 ### v1.4.1 — Multi-AI Code Review (2026-03-29)
 - **Fix**: 3 bugs found by GPT-5.4 (Codex CLI) + Gemini 2.5 (Gemini CLI) reviewing full codebase

package/bin/nexo-brain.js

@@ -1764,6 +1764,7 @@ async function main() {
     "evolution_cycle.py",
     "migrate_embeddings.py",
     "auto_close_sessions.py",
+    "client_sync.py",
     "auto_update.py",
     "tools_sessions.py",
     "tools_coordination.py",
@@ -2366,6 +2367,40 @@ ${doScan ? `- Stack: ${Object.keys(profileData.code.languages || {}).slice(0, 5)
   fs.writeFileSync(CLAUDE_SETTINGS, JSON.stringify(settings, null, 2));
   log("MCP server + 8 core hooks configured in Claude Code settings.");
 
+  const syncClientsScript = path.join(NEXO_HOME, "scripts", "nexo-sync-clients.py");
+  if (fs.existsSync(syncClientsScript)) {
+    const syncResult = spawnSync(
+      python,
+      [
+        syncClientsScript,
+        "--nexo-home", NEXO_HOME,
+        "--runtime-root", NEXO_HOME,
+        "--python", python,
+        "--operator-name", operatorName,
+        "--json",
+      ],
+      { encoding: "utf8" }
+    );
+    if (syncResult.status === 0) {
+      try {
+        const payload = JSON.parse(syncResult.stdout || "{}");
+        const clients = payload.clients || {};
+        const fmt = (name, key) => {
+          const item = clients[key] || {};
+          if (item.skipped) return `${name}: skipped`;
+          if (item.ok) return `${name}: synced`;
+          return `${name}: warning`;
+        };
+        log(`Shared brain client sync complete (${fmt("Claude Code", "claude_code")}, ${fmt("Claude Desktop", "claude_desktop")}, ${fmt("Codex", "codex")}).`);
+      } catch {
+        log("Shared brain client sync complete.");
+      }
+    } else {
+      const errMsg = (syncResult.stderr || syncResult.stdout || "").trim();
+      log(`WARN: shared brain client sync failed: ${errMsg || "unknown error"}`);
+    }
+  }
+
   // Step 7: Create schedule.json (only on fresh install) and install core processes
   log("Setting up automated processes...");
   let schedule = loadOrCreateSchedule(NEXO_HOME);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nexo-brain",
-  "version": "2.6.9",
+  "version": "2.6.10",
   "mcpName": "io.github.wazionapps/nexo",
   "description": "NEXO — local cognitive runtime for Claude Code. Persistent memory, overnight learning, recovery-aware crons, personal scripts, doctor diagnostics, startup preflight, and optional power helper.",
   "bin": {

package/src/auto_update.py

@@ -1197,6 +1197,7 @@ def _backup_runtime_tree(dest: Path = NEXO_HOME) -> str:
         "server.py", "plugin_loader.py", "knowledge_graph.py", "kg_populate.py",
         "maintenance.py", "storage_router.py", "claim_graph.py", "hnsw_index.py",
         "evolution_cycle.py", "migrate_embeddings.py", "auto_close_sessions.py",
+        "client_sync.py",
         "auto_update.py", "tools_sessions.py", "tools_coordination.py",
         "tools_reminders.py", "tools_reminders_crud.py", "tools_learnings.py",
         "tools_credentials.py", "tools_task_history.py", "tools_menu.py",
@@ -1244,6 +1245,7 @@ def _copy_runtime_from_source(src_dir: Path, repo_dir: Path, dest: Path = NEXO_H
         "server.py", "plugin_loader.py", "knowledge_graph.py", "kg_populate.py",
         "maintenance.py", "storage_router.py", "claim_graph.py", "hnsw_index.py",
         "evolution_cycle.py", "migrate_embeddings.py", "auto_close_sessions.py",
+        "client_sync.py",
         "auto_update.py", "tools_sessions.py", "tools_coordination.py",
         "tools_reminders.py", "tools_reminders_crud.py", "tools_learnings.py",
         "tools_credentials.py", "tools_task_history.py", "tools_menu.py",
@@ -1432,6 +1434,18 @@ def _run_runtime_post_sync(dest: Path = NEXO_HOME, progress_fn=None) -> tuple[bo
     if power_result.get("ok"):
         actions.append(f"power:{power_result.get('action')}")
 
+    _emit_progress(progress_fn, "Refreshing shared client configs...")
+    try:
+        from client_sync import sync_all_clients
+
+        client_sync_result = sync_all_clients(nexo_home=dest, runtime_root=dest)
+        if client_sync_result.get("ok"):
+            actions.append("client-sync")
+        else:
+            actions.append("client-sync-warning")
+    except Exception as e:
+        actions.append(f"client-sync-warning:{e}")
+
     _emit_progress(progress_fn, "Verifying runtime imports...")
     verify = subprocess.run(
         [sys.executable, "-c", "import server"],

package/src/cli.py

@@ -22,6 +22,7 @@ Entry points:
   nexo skills approve ID [--execution-level ...] [--approved-by ...] [--json]
   nexo skills featured [--limit N] [--json]
   nexo skills evolution [--json]
+  nexo clients sync [--json]
   nexo contributor status|on|off [--json]
   nexo doctor [--tier boot|runtime|deep|all] [--json] [--fix]
 """
@@ -569,6 +570,17 @@ def _update(args):
     return 0 if result.get("ok") else 1
 
 
+def _clients_sync(args):
+    from client_sync import format_sync_summary, sync_all_clients
+
+    result = sync_all_clients(nexo_home=NEXO_HOME, runtime_root=NEXO_CODE)
+    if args.json:
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+    else:
+        print(format_sync_summary(result))
+    return 0 if result.get("ok") else 1
+
+
 def _contributor_status(args):
     from public_contribution import (
         format_public_contribution_label,
@@ -861,6 +873,7 @@ Commands:
   nexo scripts list|create|classify|sync|reconcile|ensure-schedules|schedules|run|doctor|call|unschedule|remove
                                                       Personal scripts
   nexo skills list|apply|sync|approve                  Executable skills
+  nexo clients sync                                    Sync Claude Code/Desktop/Codex MCP configs
   nexo update                                          Update installed runtime
   nexo contributor status|on|off                       Public Draft PR contribution mode
   nexo dashboard on|off|status                         Web dashboard control
@@ -950,6 +963,12 @@ def main():
     update_parser = sub.add_parser("update", help="Update installed runtime")
     update_parser.add_argument("--json", action="store_true", help="JSON output")
 
+    # -- clients --
+    clients_parser = sub.add_parser("clients", help="Shared client config management")
+    clients_sub = clients_parser.add_subparsers(dest="clients_command")
+    clients_sync_p = clients_sub.add_parser("sync", help="Sync Claude Code, Claude Desktop, and Codex to the same NEXO brain")
+    clients_sync_p.add_argument("--json", action="store_true", help="JSON output")
+
     # -- doctor --
     doctor_parser = sub.add_parser("doctor", help="Unified diagnostics")
     doctor_parser.add_argument("--tier", default="boot", choices=["boot", "runtime", "deep", "all"],
@@ -1045,6 +1064,11 @@ def main():
         return _chat(args)
     elif args.command == "update":
         return _update(args)
+    elif args.command == "clients":
+        if args.clients_command == "sync":
+            return _clients_sync(args)
+        clients_parser.print_help()
+        return 0
     elif args.command == "doctor":
         return _doctor(args)
     elif args.command == "contributor":

package/src/client_sync.py

@@ -0,0 +1,327 @@
+from __future__ import annotations
+
+"""Shared client sync for Claude Code, Claude Desktop, and Codex."""
+
+import argparse
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+
+def _user_home() -> Path:
+    return Path(os.environ.get("HOME", str(Path.home()))).expanduser()
+
+
+def _default_nexo_home() -> Path:
+    return Path(os.environ.get("NEXO_HOME", str(_user_home() / ".nexo"))).expanduser()
+
+
+def _resolve_operator_name(nexo_home: Path, explicit: str = "") -> str:
+    explicit = (explicit or "").strip()
+    if explicit:
+        return explicit
+    env_name = os.environ.get("NEXO_NAME", "").strip()
+    if env_name:
+        return env_name
+    version_file = nexo_home / "version.json"
+    if version_file.is_file():
+        try:
+            return str(json.loads(version_file.read_text()).get("operator_name", "")).strip()
+        except Exception:
+            pass
+    return ""
+
+
+def _resolve_runtime_root(nexo_home: Path, runtime_root: str | os.PathLike[str] | None = None) -> Path:
+    candidates: list[Path] = []
+    if runtime_root:
+        candidates.append(Path(runtime_root).expanduser())
+    code_env = os.environ.get("NEXO_CODE", "").strip()
+    if code_env:
+        code_path = Path(code_env).expanduser()
+        candidates.extend([code_path, code_path / "src"])
+    candidates.extend([nexo_home, Path.cwd(), Path.cwd() / "src"])
+
+    seen: set[Path] = set()
+    for candidate in candidates:
+        resolved = candidate.resolve()
+        if resolved in seen:
+            continue
+        seen.add(resolved)
+        if (resolved / "server.py").is_file():
+            return resolved
+    raise FileNotFoundError(f"Could not locate runtime root with server.py (tried {len(seen)} locations)")
+
+
+def _resolve_python(nexo_home: Path, explicit: str = "") -> str:
+    candidates = [
+        explicit,
+        str(nexo_home / ".venv" / "bin" / "python3"),
+        str(nexo_home / ".venv" / "bin" / "python"),
+        str(nexo_home / ".venv" / "Scripts" / "python.exe"),
+        shutil.which("python3") or "",
+        shutil.which("python") or "",
+        sys.executable,
+    ]
+    for candidate in candidates:
+        if candidate and Path(candidate).exists():
+            return str(Path(candidate))
+    return explicit or sys.executable
+
+
+def build_server_config(
+    *,
+    nexo_home: str | os.PathLike[str] | None = None,
+    runtime_root: str | os.PathLike[str] | None = None,
+    python_path: str = "",
+    operator_name: str = "",
+) -> dict:
+    nexo_home_path = Path(nexo_home).expanduser() if nexo_home else _default_nexo_home()
+    runtime_root_path = _resolve_runtime_root(nexo_home_path, runtime_root)
+    config = {
+        "command": _resolve_python(nexo_home_path, python_path),
+        "args": [str(runtime_root_path / "server.py")],
+        "env": {
+            "NEXO_HOME": str(nexo_home_path),
+            "NEXO_CODE": str(runtime_root_path),
+        },
+    }
+    resolved_name = _resolve_operator_name(nexo_home_path, explicit=operator_name)
+    if resolved_name:
+        config["env"]["NEXO_NAME"] = resolved_name
+    return config
+
+
+def _claude_code_settings_path(home: Path | None = None) -> Path:
+    base = home or _user_home()
+    return base / ".claude" / "settings.json"
+
+
+def _claude_desktop_config_path(home: Path | None = None) -> Path:
+    base = home or _user_home()
+    if sys.platform == "darwin":
+        return base / "Library" / "Application Support" / "Claude" / "claude_desktop_config.json"
+    if os.name == "nt":
+        return base / "AppData" / "Roaming" / "Claude" / "claude_desktop_config.json"
+    return base / ".config" / "Claude" / "claude_desktop_config.json"
+
+
+def _codex_config_path(home: Path | None = None) -> Path:
+    base = home or _user_home()
+    return base / ".codex" / "config.toml"
+
+
+def _load_json_object(path: Path) -> dict:
+    if not path.is_file():
+        return {}
+    try:
+        data = json.loads(path.read_text())
+    except Exception as exc:
+        raise ValueError(f"Invalid JSON in {path}: {exc}") from exc
+    if not isinstance(data, dict):
+        raise ValueError(f"Expected JSON object in {path}")
+    return data
+
+
+def _write_json_object(path: Path, payload: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(payload, indent=2, ensure_ascii=False) + "\n")
+
+
+def _sync_json_client(path: Path, server_config: dict, label: str) -> dict:
+    payload = _load_json_object(path)
+    mcp_servers = payload.setdefault("mcpServers", {})
+    if not isinstance(mcp_servers, dict):
+        mcp_servers = {}
+        payload["mcpServers"] = mcp_servers
+    action = "updated" if "nexo" in mcp_servers else "created"
+    mcp_servers["nexo"] = server_config
+    _write_json_object(path, payload)
+    return {
+        "ok": True,
+        "client": label,
+        "action": action,
+        "path": str(path),
+    }
+
+
+def sync_claude_code(
+    *,
+    nexo_home: str | os.PathLike[str] | None = None,
+    runtime_root: str | os.PathLike[str] | None = None,
+    python_path: str = "",
+    operator_name: str = "",
+    user_home: str | os.PathLike[str] | None = None,
+) -> dict:
+    server_config = build_server_config(
+        nexo_home=nexo_home,
+        runtime_root=runtime_root,
+        python_path=python_path,
+        operator_name=operator_name,
+    )
+    return _sync_json_client(
+        _claude_code_settings_path(Path(user_home).expanduser() if user_home else None),
+        server_config,
+        "claude_code",
+    )
+
+
+def sync_claude_desktop(
+    *,
+    nexo_home: str | os.PathLike[str] | None = None,
+    runtime_root: str | os.PathLike[str] | None = None,
+    python_path: str = "",
+    operator_name: str = "",
+    user_home: str | os.PathLike[str] | None = None,
+) -> dict:
+    server_config = build_server_config(
+        nexo_home=nexo_home,
+        runtime_root=runtime_root,
+        python_path=python_path,
+        operator_name=operator_name,
+    )
+    return _sync_json_client(
+        _claude_desktop_config_path(Path(user_home).expanduser() if user_home else None),
+        server_config,
+        "claude_desktop",
+    )
+
+
+def sync_codex(
+    *,
+    nexo_home: str | os.PathLike[str] | None = None,
+    runtime_root: str | os.PathLike[str] | None = None,
+    python_path: str = "",
+    operator_name: str = "",
+    user_home: str | os.PathLike[str] | None = None,
+) -> dict:
+    nexo_home_path = Path(nexo_home).expanduser() if nexo_home else _default_nexo_home()
+    home_path = Path(user_home).expanduser() if user_home else _user_home()
+    server_config = build_server_config(
+        nexo_home=nexo_home_path,
+        runtime_root=runtime_root,
+        python_path=python_path,
+        operator_name=operator_name,
+    )
+    codex_bin = shutil.which("codex")
+    config_path = _codex_config_path(home_path)
+    if not codex_bin:
+        return {
+            "ok": True,
+            "client": "codex",
+            "skipped": True,
+            "reason": "codex binary not found in PATH",
+            "path": str(config_path),
+        }
+
+    cmd = [codex_bin, "mcp", "add", "nexo"]
+    for key, value in sorted(server_config.get("env", {}).items()):
+        cmd.extend(["--env", f"{key}={value}"])
+    cmd.extend(["--", server_config["command"], *server_config.get("args", [])])
+    env = {**os.environ, "HOME": str(home_path)}
+    result = subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+        timeout=30,
+        env=env,
+    )
+    if result.returncode != 0:
+        return {
+            "ok": False,
+            "client": "codex",
+            "path": str(config_path),
+            "error": (result.stderr or result.stdout or "codex mcp add failed").strip(),
+        }
+    return {
+        "ok": True,
+        "client": "codex",
+        "action": "updated",
+        "path": str(config_path),
+        "mode": "cli",
+    }
+
+
+def sync_all_clients(
+    *,
+    nexo_home: str | os.PathLike[str] | None = None,
+    runtime_root: str | os.PathLike[str] | None = None,
+    python_path: str = "",
+    operator_name: str = "",
+    user_home: str | os.PathLike[str] | None = None,
+) -> dict:
+    def _safe(label: str, fn) -> dict:
+        try:
+            return fn(
+                nexo_home=nexo_home,
+                runtime_root=runtime_root,
+                python_path=python_path,
+                operator_name=operator_name,
+                user_home=user_home,
+            )
+        except Exception as exc:
+            return {"ok": False, "client": label, "error": str(exc)}
+
+    results = {
+        "claude_code": _safe("claude_code", sync_claude_code),
+        "claude_desktop": _safe("claude_desktop", sync_claude_desktop),
+        "codex": _safe("codex", sync_codex),
+    }
+    ok = all(item.get("ok") or item.get("skipped") for item in results.values())
+    return {
+        "ok": ok,
+        "nexo_home": str(Path(nexo_home).expanduser() if nexo_home else _default_nexo_home()),
+        "runtime_root": str(_resolve_runtime_root(
+            Path(nexo_home).expanduser() if nexo_home else _default_nexo_home(),
+            runtime_root,
+        )),
+        "clients": results,
+    }
+
+
+def format_sync_summary(result: dict) -> str:
+    labels = {
+        "claude_code": "Claude Code",
+        "claude_desktop": "Claude Desktop",
+        "codex": "Codex",
+    }
+    lines = ["SHARED BRAIN SYNC"]
+    for key in ["claude_code", "claude_desktop", "codex"]:
+        item = result.get("clients", {}).get(key, {})
+        label = labels[key]
+        if item.get("skipped"):
+            lines.append(f"  {label}: skipped ({item.get('reason', 'not available')})")
+        elif item.get("ok"):
+            lines.append(f"  {label}: {item.get('action', 'synced')} -> {item.get('path', '')}")
+        else:
+            lines.append(f"  {label}: ERROR -> {item.get('error', 'unknown error')}")
+    return "\n".join(lines)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Sync NEXO MCP config across Claude Code, Claude Desktop, and Codex.")
+    parser.add_argument("--nexo-home", default=str(_default_nexo_home()))
+    parser.add_argument("--runtime-root", default="")
+    parser.add_argument("--python", dest="python_path", default="")
+    parser.add_argument("--operator-name", default="")
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args(argv)
+
+    result = sync_all_clients(
+        nexo_home=args.nexo_home,
+        runtime_root=args.runtime_root or None,
+        python_path=args.python_path,
+        operator_name=args.operator_name,
+    )
+    if args.json:
+        print(json.dumps(result, indent=2, ensure_ascii=False))
+    else:
+        print(format_sync_summary(result))
+    return 0 if result.get("ok") else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/plugins/update.py

@@ -584,6 +584,21 @@ def handle_update(remote: str = "origin", branch: str = "main", progress_fn=None
         except Exception as e:
             pass  # Non-critical, log in function
 
+        # Step 10: Sync shared client configs
+        try:
+            _emit_progress(progress_fn, "Refreshing shared client configs...")
+            from client_sync import sync_all_clients
+
+            client_sync_result = sync_all_clients(
+                nexo_home=NEXO_HOME,
+                runtime_root=SRC_DIR,
+                operator_name=os.environ.get("NEXO_NAME", ""),
+            )
+            if client_sync_result.get("ok"):
+                steps_done.append("client-sync")
+        except Exception:
+            pass  # Non-critical, configs can be re-synced later
+
         # Build result
         if pull_out == "Already up to date.":
             return f"Already up to date (v{old_version}). No changes pulled."
@@ -603,6 +618,8 @@ def handle_update(remote: str = "origin", branch: str = "main", progress_fn=None
             lines.append("  Crons: synced with manifest")
         if "hook-sync" in steps_done:
             lines.append("  Hooks: synced to NEXO_HOME")
+        if "client-sync" in steps_done:
+            lines.append("  Clients: Claude Code/Desktop/Codex synced")
         lines.append("")
         lines.append("MCP server restart needed to load new code.")
         return "\n".join(lines)

package/src/scripts/nexo-sync-clients.py

@@ -0,0 +1,16 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from client_sync import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/scripts/nexo-update.sh

@@ -247,6 +247,17 @@ if $CRON_SYNC_OK && [ -d "$SRC_DIR/crons" ]; then
     log "Refreshed installed crons manifest."
 fi
 
+# --- Step 9: Sync shared client configs ---
+CLIENT_SYNC="$SRC_DIR/scripts/nexo-sync-clients.py"
+if [ -f "$CLIENT_SYNC" ]; then
+    log "Syncing Claude Code, Claude Desktop, and Codex configs..."
+    if NEXO_HOME="$NEXO_HOME" NEXO_CODE="$SRC_DIR" python3 "$CLIENT_SYNC" --nexo-home "$NEXO_HOME" --runtime-root "$SRC_DIR" --json >/dev/null 2>&1; then
+        log "Shared client configs synced."
+    else
+        warn "Client config sync failed (non-fatal). Run 'nexo clients sync' later."
+    fi
+fi
+
 # --- Done ---
 echo ""
 log "========================================="