Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

fix(cc-plugin): drop --scope from plugin commands, add legacy install path (#1876)

t0saki5576bb284222
diff --git a/docs/en/agent-integrations/02-claude-code.md b/docs/en/agent-integrations/02-claude-code.md
index 884dc5fb1..8378067e0 100644
--- a/docs/en/agent-integrations/02-claude-code.md
+++ b/docs/en/agent-integrations/02-claude-code.md
@@ -54,11 +54,15 @@ Inside Claude Code, run `/mcp` after the next start — the OpenViking entry sho
From the OpenViking repo root:
```bash
-claude plugin marketplace add "$(pwd)/examples" --scope local
-claude plugin install claude-code-memory-plugin@openviking-plugins-local --scope local
+claude plugin marketplace add "$(pwd)/examples"
+claude plugin install claude-code-memory-plugin@openviking-plugins-local
```
-> Local install points Claude Code at the source directory. Edits to `scripts/`, `hooks/`, and config files take effect on the next hook invocation — no reinstall. But moving / renaming / deleting the source dir, or `git checkout`-ing to a branch without these files, breaks the plugin.
+> The plugin installs at user scope by default — active from any directory. We don't pass `--scope` because older Claude Code 2.0.x builds (e.g. 2.0.76) reject the flag.
+>
+> The marketplace entry points Claude Code at the source directory. Edits to `scripts/`, `hooks/`, and config files take effect on the next hook invocation — no reinstall. But moving / renaming / deleting the source dir, or `git checkout`-ing to a branch without these files, breaks the plugin.
+>
+> **Claude Code < 2.0?** `claude plugin` shipped in 2.0 (Oct 2025). Older builds still expose `claude mcp add` + the hooks system — the [plugin README's Legacy mode section](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md#legacy-mode-claude-code--20) shows how to wire the same functionality by hand, and the one-line installer detects the version and offers it automatically.
#### 3. Start Claude Code
diff --git a/docs/zh/agent-integrations/02-claude-code.md b/docs/zh/agent-integrations/02-claude-code.md
index 9ec9c7cb4..0a5dd5a38 100644
--- a/docs/zh/agent-integrations/02-claude-code.md
+++ b/docs/zh/agent-integrations/02-claude-code.md
@@ -54,11 +54,15 @@ type claude # 期望输出:claude is a shell function
在 OpenViking 仓库根目录执行:
```bash
-claude plugin marketplace add "$(pwd)/examples" --scope local
-claude plugin install claude-code-memory-plugin@openviking-plugins-local --scope local
+claude plugin marketplace add "$(pwd)/examples"
+claude plugin install claude-code-memory-plugin@openviking-plugins-local
```
-> 本地安装让 Claude Code 直接引用源码目录,对 `scripts/`、`hooks/`、配置文件的修改下次 hook 触发即生效,无需重装。但移动 / 重命名 / 删除源码目录,或 `git checkout` 到不含这些文件的分支,会让插件失效。
+> 默认装在 user scope —— 任何目录下都生效。这里**不显式传 `--scope`**,因为老的 Claude Code 2.0.x(比如 2.0.76)不识别这个 flag 会直接报错。
+>
+> marketplace 条目让 Claude Code 直接引用源码目录,对 `scripts/`、`hooks/`、配置文件的修改下次 hook 触发即生效,无需重装。但移动 / 重命名 / 删除源码目录,或 `git checkout` 到不含这些文件的分支,会让插件失效。
+>
+> **Claude Code < 2.0?** `claude plugin` 是 2.0(2025-10)才引入的。更老的版本仍然有 `claude mcp add` 和 hooks 系统,可以走[插件 README 的兼容模式章节](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README_CN.md#兼容模式claude-code--20)手动接同样的功能。一键安装脚本会自动检测版本并询问你是否走这条路径。
#### 3. 启动 Claude Code
diff --git a/examples/claude-code-memory-plugin/README.md b/examples/claude-code-memory-plugin/README.md
index 5b9f35c78..29061b1d9 100644
--- a/examples/claude-code-memory-plugin/README.md
+++ b/examples/claude-code-memory-plugin/README.md
@@ -51,14 +51,41 @@ If `ov.conf` is what you already maintain, the plugin reads it too — see [Conf
The repo's `examples/.claude-plugin/marketplace.json` exposes the plugin as a local marketplace entry. From the OpenViking repo root:
```bash
-claude plugin marketplace add "$(pwd)/examples" --scope user
-claude plugin install claude-code-memory-plugin@openviking-plugins-local --scope user
+claude plugin marketplace add "$(pwd)/examples"
+claude plugin install claude-code-memory-plugin@openviking-plugins-local
```
-> `--scope user` makes the plugin active from any directory. Using `--scope local` ties enablement to the current dir and the plugin shows up disabled the moment you `cd` elsewhere.
+> Both commands install at user scope by default — the plugin is active from any directory. We don't pass `--scope user` explicitly because older Claude Code 2.0.x builds (e.g. 2.0.76) reject the flag. On newer builds that do accept `--scope`, you can lift a local-scoped install to user scope with `claude plugin enable claude-code-memory-plugin@openviking-plugins-local --scope user`.
>
> The marketplace entry points Claude Code at the source directory. Edits to `scripts/`, `hooks/`, and config files take effect on the next hook invocation — no reinstall. But moving / renaming / deleting the source dir, or `git checkout`-ing to a branch without these files, breaks the plugin. A public marketplace listing for one-click install will follow.
+##### Legacy mode (Claude Code < 2.0)
+
+`claude plugin` ships in Claude Code 2.0+ (Oct 2025). Older builds still have `claude mcp add` and the hooks system, so the same functionality can be wired up by hand:
+
+```bash
+PLUGIN_DIR="$(pwd)/examples/claude-code-memory-plugin"
+
+claude mcp remove openviking -s user 2>/dev/null
+claude mcp add --scope user --transport http openviking \
+ '${OPENVIKING_URL:-http://127.0.0.1:1933}/mcp' \
+ --header 'Authorization: Bearer ${OPENVIKING_API_KEY:-}' \
+ --header 'X-OpenViking-Account: ${OPENVIKING_ACCOUNT:-}' \
+ --header 'X-OpenViking-User: ${OPENVIKING_USER:-}' \
+ --header 'X-OpenViking-Agent: ${OPENVIKING_AGENT_ID:-}'
+
+# Merge plugin hooks into ~/.claude/settings.json (with backup).
+mkdir -p ~/.claude && [ -f ~/.claude/settings.json ] || echo '{}' > ~/.claude/settings.json
+cp -p ~/.claude/settings.json ~/.claude/settings.json.bak.$(date +%s)
+sed "s|\${CLAUDE_PLUGIN_ROOT}|$PLUGIN_DIR|g" "$PLUGIN_DIR/hooks/hooks.json" > /tmp/ov-hooks.json
+jq --slurpfile h /tmp/ov-hooks.json '.hooks = ((.hooks // {}) * $h[0].hooks)' \
+ ~/.claude/settings.json > /tmp/ov-settings.json
+jq -e . /tmp/ov-settings.json >/dev/null && mv /tmp/ov-settings.json ~/.claude/settings.json
+rm -f /tmp/ov-hooks.json
+```
+
+The single-quoted `${VAR}` literals in `claude mcp add` are intentional — Claude Code expands them at MCP launch time using whatever the shell wrapper injects. Don't switch to double quotes; your shell would expand them to empty strings before the command runs. The one-line installer does all of this for you and prompts before touching `~/.claude/settings.json`.
+
#### 4. Start Claude Code
```bash
diff --git a/examples/claude-code-memory-plugin/README_CN.md b/examples/claude-code-memory-plugin/README_CN.md
index 2864e2e6e..a567231ed 100644
--- a/examples/claude-code-memory-plugin/README_CN.md
+++ b/examples/claude-code-memory-plugin/README_CN.md
@@ -51,14 +51,41 @@ curl http://localhost:1933/health # 或者你的远程 URL
仓库的 `examples/.claude-plugin/marketplace.json` 把本插件暴露为一个本地 marketplace 条目。在 OpenViking 仓库根目录:
```bash
-claude plugin marketplace add "$(pwd)/examples" --scope user
-claude plugin install claude-code-memory-plugin@openviking-plugins-local --scope user
+claude plugin marketplace add "$(pwd)/examples"
+claude plugin install claude-code-memory-plugin@openviking-plugins-local
```
-> `--scope user` 让插件在任意目录下都启用。用 `--scope local` 会把启用状态绑死在当前目录,一旦 `cd` 到别处插件就显示 disabled,需要手动 enable。
+> 两条命令默认都装在 user scope —— 插件在任何目录下都生效。这里**不显式传 `--scope user`**,因为老的 Claude Code 2.0.x(比如 2.0.76)不识别这个 flag 会直接报错。在支持 `--scope` 的新版本上,如果装完发现落到了 local scope,可以跑一次 `claude plugin enable claude-code-memory-plugin@openviking-plugins-local --scope user` 提升到 user scope。
>
> marketplace 条目让 Claude Code 直接引用源码目录,对 `scripts/`、`hooks/`、配置文件的修改下次 hook 触发即生效,无需重装。但移动 / 重命名 / 删除源码目录,或 `git checkout` 到不含这些文件的分支,会立刻让插件失效。后续会发布公开 marketplace 以支持一键安装。
+##### 兼容模式(Claude Code < 2.0)
+
+`claude plugin` 子命令是 Claude Code 2.0(2025-10)才引入的。再老的版本只有 `claude mcp add` 和 hooks 系统,但仍然能手动接出同样的功能:
+
+```bash
+PLUGIN_DIR="$(pwd)/examples/claude-code-memory-plugin"
+
+claude mcp remove openviking -s user 2>/dev/null
+claude mcp add --scope user --transport http openviking \
+ '${OPENVIKING_URL:-http://127.0.0.1:1933}/mcp' \
+ --header 'Authorization: Bearer ${OPENVIKING_API_KEY:-}' \
+ --header 'X-OpenViking-Account: ${OPENVIKING_ACCOUNT:-}' \
+ --header 'X-OpenViking-User: ${OPENVIKING_USER:-}' \
+ --header 'X-OpenViking-Agent: ${OPENVIKING_AGENT_ID:-}'
+
+# 把插件 hooks 合并进 ~/.claude/settings.json(自动备份)
+mkdir -p ~/.claude && [ -f ~/.claude/settings.json ] || echo '{}' > ~/.claude/settings.json
+cp -p ~/.claude/settings.json ~/.claude/settings.json.bak.$(date +%s)
+sed "s|\${CLAUDE_PLUGIN_ROOT}|$PLUGIN_DIR|g" "$PLUGIN_DIR/hooks/hooks.json" > /tmp/ov-hooks.json
+jq --slurpfile h /tmp/ov-hooks.json '.hooks = ((.hooks // {}) * $h[0].hooks)' \
+ ~/.claude/settings.json > /tmp/ov-settings.json
+jq -e . /tmp/ov-settings.json >/dev/null && mv /tmp/ov-settings.json ~/.claude/settings.json
+rm -f /tmp/ov-hooks.json
+```
+
+`claude mcp add` 的所有参数**必须用单引号**保留 `${VAR}` 字面量 —— Claude Code 在启动 MCP server 时才展开它们,用的就是 shell wrapper 注入的环境变量。换成双引号 shell 会提前把它们展开成空串,配置就废了。一键安装脚本会自动做这一切,并在改 `~/.claude/settings.json` 前提示你。
+
#### 4. 启动 Claude Code
```bash
diff --git a/examples/claude-code-memory-plugin/setup-helper/install.sh b/examples/claude-code-memory-plugin/setup-helper/install.sh
index 6b255aace..bc4ef305f 100755
--- a/examples/claude-code-memory-plugin/setup-helper/install.sh
+++ b/examples/claude-code-memory-plugin/setup-helper/install.sh
@@ -10,7 +10,10 @@
# 2. Set up ~/.openviking/ovcli.conf — reuse if present, prompt otherwise.
# 3. Clone (or refresh) the OpenViking repo to ~/.openviking/openviking-repo.
# 4. Add a `claude` shell function to your rc that injects creds at invocation.
-# 5. Install the plugin via `claude plugin marketplace add` + `claude plugin install`.
+# 5. Install the plugin. On Claude Code >= 2.0 (with `claude plugin` support) we
+# use marketplace + plugin install. On older builds — or if marketplace is
+# unavailable — we fall back to legacy mode: `claude mcp add` + a merge into
+# ~/.claude/settings.json.
#
# Env overrides:
# OPENVIKING_HOME default: $HOME/.openviking
@@ -205,37 +208,153 @@ EOF
fi
# ----- 5. Plugin install -----
+#
+# `claude plugin` was introduced in Claude Code 2.0 (2025-10). Older builds only
+# expose `claude mcp add` and the hooks system. We detect the major version and
+# offer a legacy install path that wires the same functionality through
+# `claude mcp add` + a merge into ~/.claude/settings.json.
+#
+# Note on `--scope`:
+# - `claude mcp add --scope user` has been supported since MCP first shipped,
+# and the default (`local`) ties the server to one project, so we DO pass it.
+# - `claude plugin install` / `claude plugin marketplace add` already default to
+# user scope, and the `--scope` flag is rejected by older 2.0.x builds (e.g.
+# 2.0.76). We omit it.
heading '5. Plugin install'
-if [ "$CLAUDE_AVAILABLE" -eq 1 ]; then
- # Use --scope user so the plugin is active from any directory, not just $REPO_DIR.
- # `local` scope binds enablement to $REPO_DIR's .claude/settings.local.json, which
- # surfaces as "disabled" the moment the user `cd`s elsewhere and forces a manual
- # `claude plugin enable` post-install.
+# Probe for `claude plugin` support directly rather than parsing --version output.
+# The version-string format isn't a stable contract; the subcommand's existence is.
+has_plugin_subcommand() {
+ claude plugin --help >/dev/null 2>&1
+}
+
+install_legacy() {
+ local plugin_dir="$REPO_DIR/examples/claude-code-memory-plugin"
+ local hooks_src="$plugin_dir/hooks/hooks.json"
+ local settings="$HOME/.claude/settings.json"
+ local ts; ts=$(date +%Y%m%d-%H%M%S)
+
+ info "Legacy mode: registering MCP server + merging hooks into $settings"
+
+ # 1) MCP server. Single-quoted ${VAR} literals so Claude Code expands them at
+ # MCP launch time using whatever the rc wrapper has injected.
+ info 'claude mcp add openviking (user scope)'
+ claude mcp remove openviking -s user >/dev/null 2>&1 || true
+ claude mcp add --scope user --transport http openviking \
+ '${OPENVIKING_URL:-http://127.0.0.1:1933}/mcp' \
+ --header 'Authorization: Bearer ${OPENVIKING_API_KEY:-}' \
+ --header 'X-OpenViking-Account: ${OPENVIKING_ACCOUNT:-}' \
+ --header 'X-OpenViking-User: ${OPENVIKING_USER:-}' \
+ --header 'X-OpenViking-Agent: ${OPENVIKING_AGENT_ID:-}' || {
+ err 'claude mcp add failed'
+ return 1
+ }
+
+ # 2) Hooks: replace ${CLAUDE_PLUGIN_ROOT} (only expanded by 2.0+ plugin loader)
+ # with an absolute path, then merge into ~/.claude/settings.json. Back up
+ # first; verify the merged JSON before overwriting.
+ if [ ! -f "$hooks_src" ]; then
+ err "hooks source not found: $hooks_src"
+ return 1
+ fi
+ mkdir -p "$HOME/.claude"
+ [ -f "$settings" ] || echo '{}' > "$settings"
+ cp -p "$settings" "$settings.bak.$ts"
+ info "Backup: $settings.bak.$ts"
+
+ # mktemp instead of `$$` — predictable PID-based names are vulnerable to
+ # symlink races on shared /tmp.
+ local tmp_h tmp_s
+ tmp_h=$(mktemp "${TMPDIR:-/tmp}/ov-hooks.XXXXXX") || { err 'mktemp failed'; return 1; }
+ tmp_s=$(mktemp "${TMPDIR:-/tmp}/ov-settings.XXXXXX") || { err 'mktemp failed'; rm -f "$tmp_h"; return 1; }
+
+ # Replace ${CLAUDE_PLUGIN_ROOT} via jq, not sed — $plugin_dir comes from a
+ # user-configurable env var and may contain &, |, or \ which would corrupt
+ # sed substitution.
+ if ! jq --arg root "$plugin_dir" \
+ 'walk(if type == "string" then gsub("\\$\\{CLAUDE_PLUGIN_ROOT\\}"; $root) else . end)' \
+ "$hooks_src" > "$tmp_h" 2>/dev/null; then
+ err "expanding CLAUDE_PLUGIN_ROOT in $hooks_src failed"
+ rm -f "$tmp_h" "$tmp_s"
+ return 1
+ fi
+
+ # Shallow merge — keep user's other hook events; same-event keys get overwritten.
+ # Explicit error branch so a malformed settings.json doesn't kill the whole
+ # script via `set -e` and skip our cleanup.
+ if ! jq --slurpfile h "$tmp_h" '.hooks = ((.hooks // {}) * $h[0].hooks)' \
+ "$settings" > "$tmp_s" 2>/dev/null; then
+ err "merging hooks into $settings failed; original untouched (intermediate: $tmp_s)"
+ rm -f "$tmp_h"
+ return 1
+ fi
+ mv "$tmp_s" "$settings"
+ rm -f "$tmp_h"
+ info 'hooks merged'
+}
+
+install_modern() {
+ # `--scope` intentionally omitted. Default scope is already user; passing it
+ # breaks older 2.0.x builds that don't recognize the flag.
info 'claude plugin marketplace add'
- ( cd "$REPO_DIR" && claude plugin marketplace add "$REPO_DIR/examples" --scope user ) || \
+ ( cd "$REPO_DIR" && claude plugin marketplace add "$REPO_DIR/examples" ) || \
warn 'marketplace add returned non-zero (likely already added) — continuing'
info 'claude plugin install'
- ( cd "$REPO_DIR" && claude plugin install claude-code-memory-plugin@openviking-plugins-local --scope user )
- # Belt-and-suspenders: make sure it ends up enabled even if `install` left it
- # in a disabled state (observed on some Claude Code versions).
- claude plugin enable claude-code-memory-plugin@openviking-plugins-local --scope user >/dev/null 2>&1 || true
+ ( cd "$REPO_DIR" && claude plugin install claude-code-memory-plugin@openviking-plugins-local ) || {
+ warn 'plugin install failed — falling back to legacy mode'
+ install_legacy
+ return $?
+ }
+ # Belt-and-suspenders: ensure enabled even if `install` left it disabled.
+ claude plugin enable claude-code-memory-plugin@openviking-plugins-local >/dev/null 2>&1 || true
+}
+
+USE_LEGACY=0
+if [ "$CLAUDE_AVAILABLE" -eq 1 ] && ! has_plugin_subcommand; then
+ warn "This Claude Code build doesn't expose 'claude plugin' (introduced in 2.0)."
+ ask 'Use legacy compatibility mode (claude mcp add + settings.json merge)? [Y/n] '
+ read -r reply || reply=""
+ case "$reply" in
+ n|N|no|No|NO)
+ warn "Skipping plugin install. Upgrade to Claude Code >= 2.0 and re-run."
+ CLAUDE_AVAILABLE=0
+ ;;
+ *) USE_LEGACY=1 ;;
+ esac
+fi
+
+if [ "$CLAUDE_AVAILABLE" -eq 1 ]; then
+ if [ "$USE_LEGACY" -eq 1 ]; then
+ install_legacy
+ else
+ install_modern
+ fi
else
warn "Run these manually after installing Claude Code:"
warn " cd \"$REPO_DIR\""
- warn ' claude plugin marketplace add "$(pwd)/examples" --scope user'
- warn ' claude plugin install claude-code-memory-plugin@openviking-plugins-local --scope user'
+ warn ' claude plugin marketplace add "$(pwd)/examples"'
+ warn ' claude plugin install claude-code-memory-plugin@openviking-plugins-local'
fi
# ----- Done -----
+#
+# We can't auto-source the rc into the user's shell — this script runs in a
+# subshell (e.g. `bash <(curl ...)`), so any export/source we do here dies
+# when the script exits. The user has to run `source` themselves, hence the
+# bold callout below. (`source <(curl ...)` would work but is unsafe to
+# recommend — it pipes remote code straight into the user's interactive shell.)
heading 'Done!'
info "Source: $REPO_DIR"
info "Config: $OVCLI_CONF"
[ -n "$RC" ] && info "Shell rc: $RC"
printf '\n'
-info 'Next:'
-[ -n "$RC" ] && info " source $RC # or open a new shell"
+if [ -n "$RC" ]; then
+ printf '%s%sNext — run this in your shell to pick up the wrapper:%s\n' "$BOLD" "$YELLOW" "$RESET"
+ printf ' %s%ssource %s%s\n' "$BOLD" "$CYAN" "$RC" "$RESET"
+ printf ' (or just open a new terminal window)\n\n'
+fi
+info 'Then:'
info ' claude # start Claude Code'
info ' /mcp # inside Claude Code, verify the OpenViking entry'