From 8cb3330a873d93c4828d35e9819ec832ac2f7d1a Mon Sep 17 00:00:00 2001 From: CCLCK <84182037+CCLCK@users.noreply.github.com> Date: Sat, 11 Apr 2026 16:24:25 +0800 Subject: [PATCH] Add global Codex integration bootstrap docs --- docs/global-codex-integration.md | 91 +++++++++++++++++++++++++ scripts/install-global-codex-openspace | 93 ++++++++++++++++++++++++++ 2 files changed, 184 insertions(+) create mode 100644 docs/global-codex-integration.md create mode 100644 scripts/install-global-codex-openspace diff --git a/docs/global-codex-integration.md b/docs/global-codex-integration.md new file mode 100644 index 0000000..5c5e221 --- /dev/null +++ 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//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` diff --git a/scripts/install-global-codex-openspace b/scripts/install-global-codex-openspace new file mode 100644 index 0000000..1ff0b27 --- /dev/null +++ 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" <&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" <&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 <