Add global Codex integration bootstrap docs

2026-08-28 05:15:00 +00:00 · 2026-04-11 16:24:25 +08:00 · 2026-04-11 16:24:25 +08:00 · 8cb3330a87
commit 8cb3330a87
parent 8834a75b08
2 changed files with 184 additions and 0 deletions
--- a/docs/global-codex-integration.md
+++ b/docs/global-codex-integration.md
@ -0,0 +1,91 @@
+# Global Codex Integration
+
+This document records the machine-wide Codex integration used in the local customized OpenSpace setup.
+
+## What Is Global vs Repo-Tracked
+
+### Repo-tracked
+
+These are versioned in this repository:
+
+- OpenSpace runtime changes
+- split routing for main LLM vs skill embeddings
+- project launchers under `scripts/`
+- integration docs under `docs/`
+- installer for global MCP wrappers:
+  - `scripts/install-global-codex-openspace`
+
+### Local-only
+
+These live under `~/.codex` on the local machine and are intentionally not committed directly:
+
+- `~/.codex/config.toml`
+- `~/.codex/AGENTS.md`
+- `~/.codex/bin/openspace-global-mcp`
+- `~/.codex/bin/openspace-evolution-global-mcp`
+
+These files are machine-specific because they may contain:
+
+- absolute local paths
+- user-specific Codex settings
+- local MCP wiring
+- secrets or provider-specific credentials
+
+## Why `.mcp.json` Was Not Committed
+
+The repo-local `.mcp.json` is also intentionally excluded from GitHub because it is a local override with:
+
+- absolute paths into this machine
+- host-agent-specific skill directories
+- local workflow assumptions
+
+That file is useful for local experimentation, but it is not the stable source of truth for the global Codex integration.
+
+## Canonical Global Setup
+
+The intended machine-wide setup is:
+
+1. Global Codex config points MCP servers to:
+   - `~/.codex/bin/openspace-global-mcp`
+   - `~/.codex/bin/openspace-evolution-global-mcp`
+2. Those wrapper scripts:
+   - detect the current project directory
+   - normalize it to the git repo root when possible
+   - set `OPENSPACE_WORKSPACE`
+   - route project skills to `~/.codex/projects/<repo>/skills`
+   - include common global skills from `~/.codex/skills`
+3. Global `~/.codex/AGENTS.md` tells Codex:
+   - to prefer project skill routing
+   - to auto-run sidecar evolution for non-trivial repo work
+   - to treat missing `git init` as a repo bootstrap issue
+
+## Reinstalling the Global Wrappers
+
+Use:
+
+```bash
+cd /path/to/OpenSpace
+./scripts/install-global-codex-openspace
+```
+
+This script recreates:
+
+- `~/.codex/bin/openspace-global-mcp`
+- `~/.codex/bin/openspace-evolution-global-mcp`
+
+It does **not** overwrite your `~/.codex/config.toml` or `~/.codex/AGENTS.md`.
+
+## Practical Outcome
+
+With the global integration in place:
+
+- opening a new project in Codex does not require per-project `.mcp.json`
+- OpenSpace MCP is available globally
+- OpenSpace evolution MCP is available globally
+- repo-scoped skill routing and sidecar evolution use the current project automatically
+
+## Related Docs
+
+- `docs/current-routing-flow.md`
+- `docs/release-note-local-customization.md`
+- `docs/codex-desktop-sidecar-evolution.md`
--- a/scripts/install-global-codex-openspace
+++ b/scripts/install-global-codex-openspace
@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd -- "$SCRIPT_DIR/.." && pwd)"
+REPO_PYTHON="$REPO_ROOT/.venv/bin/python"
+CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
+BIN_DIR="$CODEX_HOME/bin"
+
+if [[ ! -x "$REPO_PYTHON" ]]; then
+  echo "Missing OpenSpace Python runtime: $REPO_PYTHON" >&2
+  exit 1
+fi
+
+mkdir -p "$BIN_DIR"
+
+cat > "$BIN_DIR/openspace-global-mcp" <<EOF
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_ROOT="$REPO_ROOT"
+REPO_PYTHON="\$REPO_ROOT/.venv/bin/python"
+
+if [[ ! -x "\$REPO_PYTHON" ]]; then
+  echo "Missing OpenSpace Python runtime: \$REPO_PYTHON" >&2
+  exit 1
+fi
+
+workspace="\${OPENSPACE_WORKSPACE:-\$PWD}"
+if git_root="\$(git -C "\$workspace" rev-parse --show-toplevel 2>/dev/null)"; then
+  workspace="\$git_root"
+fi
+
+project_name="\$(basename "\$workspace")"
+if [[ -z "\$project_name" || "\$project_name" == "/" || "\$project_name" == "." ]]; then
+  project_name="default"
+fi
+
+project_skill_dir="\${HOME}/.codex/projects/\${project_name}/skills"
+mkdir -p "\$project_skill_dir" "\${HOME}/.codex/skills"
+
+export OPENSPACE_WORKSPACE="\$workspace"
+export OPENSPACE_HOST_SKILL_DIRS="\${OPENSPACE_HOST_SKILL_DIRS:-\${project_skill_dir},\${HOME}/.codex/skills}"
+
+exec "\$REPO_PYTHON" -m openspace.mcp_server --transport stdio
+EOF
+
+cat > "$BIN_DIR/openspace-evolution-global-mcp" <<EOF
+#!/usr/bin/env bash
+set -euo pipefail
+
+REPO_ROOT="$REPO_ROOT"
+REPO_PYTHON="\$REPO_ROOT/.venv/bin/python"
+
+if [[ ! -x "\$REPO_PYTHON" ]]; then
+  echo "Missing OpenSpace Python runtime: \$REPO_PYTHON" >&2
+  exit 1
+fi
+
+workspace="\${OPENSPACE_WORKSPACE:-\$PWD}"
+if git_root="\$(git -C "\$workspace" rev-parse --show-toplevel 2>/dev/null)"; then
+  workspace="\$git_root"
+fi
+
+export OPENSPACE_WORKSPACE="\$workspace"
+
+project_name="\$(basename "\$OPENSPACE_WORKSPACE")"
+if [[ -z "\$project_name" || "\$project_name" == "/" || "\$project_name" == "." ]]; then
+  project_name="default"
+fi
+
+project_skill_dir="\${HOME}/.codex/projects/\${project_name}/skills"
+mkdir -p "\$project_skill_dir" "\${HOME}/.codex/skills"
+
+export OPENSPACE_HOST_SKILL_DIRS="\${OPENSPACE_HOST_SKILL_DIRS:-\${project_skill_dir},\${HOME}/.codex/skills}"
+
+exec "\$REPO_PYTHON" -m openspace.evolution_mcp_server --transport stdio
+EOF
+
+chmod +x "$BIN_DIR/openspace-global-mcp" "$BIN_DIR/openspace-evolution-global-mcp"
+
+cat <<EOF
+Installed:
+- $BIN_DIR/openspace-global-mcp
+- $BIN_DIR/openspace-evolution-global-mcp
+
+Next:
+1. Point your global ~/.codex/config.toml MCP entries at those two wrapper scripts.
+2. Keep your global ~/.codex/AGENTS.md rules in sync with the repo docs.
+
+Reference:
+- $REPO_ROOT/docs/global-codex-integration.md
+EOF