docs(plugin/codex): dedicated agent-integrations page (zh+en) + fix MCP startup#2019
Merged
Merged
Conversation
…tartup Follow-up to volcengine#1957. Lifts Codex out of `04-other-plugins.md` into its own `04-codex.md` (en + zh) with full install steps, configuration, hook behavior, and troubleshooting — mirrors the shape of `02-claude-code.md`. Renumbers `04-other-plugins.md` → `05-` and `05-langchain-langgraph.md` → `06-`. Overview tables in both locales updated; cross-refs fixed. Also fixes two install/runtime bugs surfaced while validating the fresh installer flow against the merged PR: 1. **Stale repo clone**: `setup-helper/install.sh` previously skipped the clone if `~/.openviking/openviking-repo` already existed, so a user who installed before volcengine#1957 merged ended up with a pre-PR plugin checkout (no `scripts/`, no `servers/memory-server.js`). The installer now `git fetch + reset --hard` an existing checkout to `$REPO_REF` (default `main`), matching the claude-code installer pattern. 2. **`${CODEX_PLUGIN_ROOT}` not expanded in `.mcp.json`**: Codex 0.130 does not substitute env vars in `.mcp.json` `args`/`env` and does not always inject `CODEX_PLUGIN_ROOT` into MCP child env. The literal string `${CODEX_PLUGIN_ROOT}` was being passed to node, which then tried to resolve `${CODEX_PLUGIN_ROOT}/scripts/start-memory-server.mjs` against codex's cwd and failed with `MODULE_NOT_FOUND`. Fix: - `.mcp.json`: `args: ["scripts/start-memory-server.mjs"]` + `cwd: "."` (matches the syntax 0.1.0 used, which Codex does honor) - `scripts/runtime-common.mjs`: derive plugin root from `import.meta.url` as a fallback so the launcher works regardless of whether `CODEX_PLUGIN_ROOT` is set in the spawn env Bumps plugin to 0.4.1 (package.json + plugin.json + lockfile) since the runtime-common.mjs change invalidates the install-state hash and forces a re-install of node_modules into the per-user runtime data root.
PR Reviewer Guide 🔍Here are some key observations to aid the review process:
|
PR Code Suggestions ✨No code suggestions found for the PR. |
There was a problem hiding this comment.
Pull request overview
This PR improves the Codex memory plugin reliability and documentation by (1) splitting Codex into its own dedicated agent-integration page (EN+ZH) and renumbering the agent-integration docs accordingly, and (2) fixing MCP startup for Codex 0.130 by avoiding unsupported env-var substitution in .mcp.json and adding a robust plugin-root fallback in the runtime launcher. It also hardens the installer to refresh an existing repo checkout to prevent stale installs.
Changes:
- Docs: Add dedicated Codex integration pages (EN+ZH), renumber agent-integration pages, and update overview tables/cross-links.
- MCP startup fix: Switch
.mcp.jsontocwd: "."+ relative launcher path, and add animport.meta.url-based fallback for plugin root resolution. - Installer: Refresh existing
$REPO_DIRviagit fetch+reset --hardand bump plugin version to0.4.1.
Reviewed changes
Copilot reviewed 15 out of 17 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| examples/codex-memory-plugin/VERIFICATION.md | Bump verification SOP version reference to 0.4.1. |
| examples/codex-memory-plugin/setup-helper/install.sh | Add repo ref override and refresh existing checkout before installing. |
| examples/codex-memory-plugin/scripts/runtime-common.mjs | Add plugin-root fallback derived from import.meta.url for more reliable launches. |
| examples/codex-memory-plugin/README.md | Update cache prefill example to 0.4.1. |
| examples/codex-memory-plugin/package.json | Bump plugin version to 0.4.1. |
| examples/codex-memory-plugin/package-lock.json | Bump locked package version metadata to 0.4.1. |
| examples/codex-memory-plugin/.mcp.json | Stop using ${CODEX_PLUGIN_ROOT}; use relative launcher path + cwd. |
| examples/codex-memory-plugin/.codex-plugin/plugin.json | Bump plugin version to 0.4.1. |
| docs/en/agent-integrations/01-overview.md | Update integration index to new Codex + renumbered pages. |
| docs/en/agent-integrations/04-codex.md | New dedicated Codex integration guide (EN). |
| docs/en/agent-integrations/05-other-plugins.md | New/renumbered “Other Plugins” page (EN). |
| docs/en/agent-integrations/06-langchain-langgraph.md | New/renumbered LangChain/LangGraph integration page (EN). |
| docs/en/agent-integrations/04-other-plugins.md | Remove old combined “Other Plugins” page (EN) after split/renumber. |
| docs/zh/agent-integrations/01-overview.md | Update integration index to include Codex and renumbered pages. |
| docs/zh/agent-integrations/04-codex.md | New dedicated Codex integration guide (ZH). |
| docs/zh/agent-integrations/05-other-plugins.md | Remove old Codex blurb from “Other Plugins” and update scope (ZH). |
| docs/zh/agent-integrations/06-langchain-langgraph.md | Update cross-link to the renumbered EN page. |
Files not reviewed (1)
- examples/codex-memory-plugin/package-lock.json: Language not supported
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…UGIN_ROOT}
Same root cause as the .mcp.json fix in the previous commit: Codex 0.130
does not expand ${CODEX_PLUGIN_ROOT} in hooks.json `command` strings. The
shell that runs the hook sees the literal ${CODEX_PLUGIN_ROOT} and expands
it to "" (or leaves it literal), so node tries to load `/scripts/...mjs`
and exits 1.
Symptom in the chat UI:
• SessionStart hook (failed) error: hook exited with code 1
• UserPromptSubmit hook (failed)
• Stop hook (failed)
Fix: use `./scripts/<name>.mjs` paths, matching the pattern Codex's own
bundled plugins (e.g. figma) use. Codex's hook dispatcher resolves these
relative to the plugin root (where hooks.json lives).
The MCP launcher fix from the prior commit already handles the same class
of bug for .mcp.json; this catches the hooks path.
…l time
Previous fix (relative ./scripts/...) was based on the figma example but
empirically does not work on Codex 0.130: the hook subprocess runs with
cwd = user's cwd (not plugin root) and CODEX_PLUGIN_ROOT is NOT injected
into the env. So both ${CODEX_PLUGIN_ROOT}/scripts/foo.mjs and
./scripts/foo.mjs resolve to the wrong absolute path and node exits 1.
Verified with a probe shell script wired into hooks.json:
argv: /tmp/codex-hook-probe.sh SessionStart
cwd: /Users/<user>
CODEX_PLUGIN_ROOT: <unset>
CODEX_PLUGIN_DATA: <unset>
(The "Under-development features are incomplete" banner Codex prints when
plugin_hooks is enabled is real - the hook env wiring is unfinished in
0.130.)
Fix: keep the source hooks.json as a template (uses __OPENVIKING_PLUGIN_ROOT__
placeholder) and have install.sh sed-render the cache copy with the
absolute $CACHE_DIR path on every install. The cached hooks.json is now
fully self-contained absolute-path commands; the repo's checked-in copy
stays portable.
.mcp.json is unaffected: Codex 0.130 does honor the `cwd: "."` field for
MCP servers, so relative args resolve against plugin root there.
Empirically the auto-recall hook can take 0.8s–4s end-to-end (depending on result count and remote OV latency), and Codex 0.130 sometimes adds 4-5s of spawn overhead before our script even starts. The original 8s budget was borderline and produced spurious "hook timed out after 8s" UI errors on slow paths even when the recall would have succeeded. 15s matches the auto-recall internal timeoutMs default (config.mjs:186) and gives enough headroom for spawn-time variance without holding the user's input noticeably longer in the worst case.
Per review feedback: the claude-code installer uses OPENVIKING_REPO_BRANCH for the same purpose. Aliasing both names lets users reuse one env var across installers without remembering which plugin uses which name. Precedence: OPENVIKING_REPO_REF > OPENVIKING_REPO_BRANCH > "main".
ZaynJarvis
approved these changes
May 13, 2026
t0saki
changed the title
t0saki
changed the title
9 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Follow-up to #1957.
Docs
Lifts Codex out of
04-other-plugins.mdinto its own dedicated04-codex.md(en + zh) with install steps, configuration, hook behavior, MCP tools, and troubleshooting. Mirrors the shape of02-claude-code.mdand brings the zh version up to parity (previously the zh page still described Codex as a tiny MCP-only plugin with justfind/remember). Renumbers04-other-plugins.md→05-and05-langchain-langgraph.md→06-; overview tables in both locales updated.Plugin fixes (validated against Codex 0.130.0)
PR #1957 used
${CODEX_PLUGIN_ROOT}substitution in both.mcp.jsonandhooks.json, but empirically Codex 0.130 does not expand that placeholder, does not injectCODEX_PLUGIN_ROOTinto MCP/hook subprocess env, and runs hooks withcwd = user's cwd(not the plugin root). So both the MCP launcher and all four hooks fail to load.Probe data:
Fixes:
.mcp.json: switch tocwd: "."+ relative arg.scripts/runtime-common.mjs: derivepluginRootfromimport.meta.urlas fallback for the MCP launcher.hooks/hooks.json: kept as a template with__OPENVIKING_PLUGIN_ROOT__placeholders;setup-helper/install.shsed-renders them to absolute cache paths at install time.setup-helper/install.sh: when$REPO_DIRalready exists,git fetch --depth 1 origin <ref>+reset --hard FETCH_HEADinstead of silently reusing whatever's already there. Accepts bothOPENVIKING_REPO_REFandOPENVIKING_REPO_BRANCHas aliases for parity with the claude-code installer.UserPromptSubmithook timeout: 8s → 15s. Benchmarked recall as 0.8–3.7s on a warm node, but Codex 0.130 adds variable spawn overhead; 8s produced spurioushook timed out after 8serrors.Plugin bumped to 0.4.1 (package.json / package-lock.json / .codex-plugin/plugin.json / README / VERIFICATION.md).