feat(codex): install session-start hook

Add a Codex installer and doctor command that manage Lumen MCP registration, shared skills, the Codex hooks feature flag, and a user-level SessionStart hook for proactive index warmup.

Keep the installer aligned with the upstream v0.0.40 launcher split by using scripts/run on POSIX and scripts/run.cmd on Windows, while still detecting legacy scripts/run.sh hook entries for cleanup.

Author: def324

.codex/INSTALL.md

@@ -1,7 +1,7 @@
 # Installing Lumen for Codex
 
 Enable Lumen in Codex with native skill discovery plus a registered MCP
-server.
+server and Codex startup hooks.
 
 ## Prerequisites
 
@@ -16,56 +16,77 @@ server.
    git clone https://github.com/ory/lumen.git "$CODEX_HOME/lumen"
    ```
 
-2. Create the skills symlink:
+2. Run the Codex installer:
    ```bash
-   mkdir -p "$HOME/.agents/skills"
-   ln -s "$CODEX_HOME/lumen/skills" "$HOME/.agents/skills/lumen"
+   "$CODEX_HOME/lumen/scripts/run" codex install
    ```
 
-3. Register the MCP server:
-   ```bash
-   codex mcp add lumen -- "$CODEX_HOME/lumen/scripts/run" stdio
-   ```
+3. Restart Codex.
 
-4. Restart Codex.
+The installer enables Codex hooks in `config.toml`, registers the `lumen` MCP
+server, links or copies the shared Lumen skills into Codex's user skill
+directory, and installs a user-level Codex `SessionStart` hook. That hook runs
+on startup, resume, and clear events and reuses Lumen's background indexer to
+proactively warm the project index.
 
 ## Windows (PowerShell)
 
 ```powershell
 $codexHome = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { Join-Path $env:USERPROFILE ".codex" }
 git clone https://github.com/ory/lumen.git "$codexHome\lumen"
-New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.agents\skills" | Out-Null
-cmd /c mklink /J "$env:USERPROFILE\.agents\skills\lumen" "$codexHome\lumen\skills"
-codex mcp add lumen -- "$codexHome\lumen\scripts\run.cmd" stdio
+cmd /c "$codexHome\lumen\scripts\run.cmd" codex install
 ```
 
+Restart Codex after the installer completes.
+
 ## Migrating from the old repo-local plugin
 
 If you previously used the repo-local Codex marketplace package:
 
 1. Remove the old plugin from Codex's plugin UI.
-2. Register the MCP server with `codex mcp add` as above.
-3. Create the `~/.agents/skills/lumen` symlink.
-4. Restart Codex.
+2. Run `"$CODEX_HOME/lumen/scripts/run" codex install`.
+3. Restart Codex.
+
+If you previously hand-edited Codex MCP or hook configuration, remove stale
+manual entries after confirming the installer-managed configuration works. The
+installer owns the user-level Codex MCP registration, skill link or copy, and
+`hooks.json` `SessionStart` entry for Lumen.
 
 ## Verify
 
 ```bash
+"${CODEX_HOME:-$HOME/.codex}/lumen/scripts/run" codex doctor
 codex mcp get lumen
-ls -la "$HOME/.agents/skills/lumen"
 ```
 
 ## Updating
 
 ```bash
 cd "${CODEX_HOME:-$HOME/.codex}/lumen" && git pull
+"${CODEX_HOME:-$HOME/.codex}/lumen/scripts/run" codex install
 ```
 
 ## Uninstalling
 
 ```bash
 codex mcp remove lumen
-rm "$HOME/.agents/skills/lumen"
+skills="$HOME/.agents/skills/lumen"
+if [ -L "$skills" ]; then
+  target="$(readlink "$skills")"
+  case "$target" in
+    */lumen/skills) rm "$skills" ;;
+    *) echo "Refusing to remove non-Lumen skills link: $skills -> $target" >&2 ;;
+  esac
+elif [ -f "$skills/.lumen-skills-source" ]; then
+  rm -rf "$skills"
+else
+  echo "No installer-managed Lumen skills path found at $skills" >&2
+fi
 ```
 
-Optionally delete the clone: `rm -rf "${CODEX_HOME:-$HOME/.codex}/lumen"`.
+Remove the Lumen `SessionStart` group from
+`${CODEX_HOME:-$HOME/.codex}/hooks.json` if you want to remove the startup hook
+as well. If you no longer use any Codex hooks, you can also remove
+`codex_hooks = true` from the `[features]` table in
+`${CODEX_HOME:-$HOME/.codex}/config.toml`. Optionally delete the clone:
+`rm -rf "${CODEX_HOME:-$HOME/.codex}/lumen"`.

README.md

@@ -81,9 +81,10 @@ _Claude Code asking about the
    [OpenCode](https://opencode.ai/)
 
 **Note:** Installation differs by platform. Claude Code is installed from a
-plugin marketplace. Codex uses a local MCP server plus native skill discovery.
-OpenCode installs from npm. Cursor packaging is shipped in this repository and
-is ready for Cursor's plugin distribution workflow.
+plugin marketplace. Codex uses an installer that configures MCP, shared skills,
+and a user-level startup hook. OpenCode installs from npm. Cursor packaging is
+shipped in this repository and is ready for Cursor's plugin distribution
+workflow.
 
 **Install:**
 
@@ -113,29 +114,20 @@ skill or the Lumen `semantic_search` tool.
 
 **Codex**
 
-Quick install:
+Follow the Codex install guide:
 
-```text
-Fetch and follow instructions from https://raw.githubusercontent.com/ory/lumen/refs/heads/main/.codex/INSTALL.md
-```
-
-Manual install:
-
-```bash
-CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"
-git clone https://github.com/ory/lumen.git "$CODEX_HOME/lumen"
-mkdir -p "$HOME/.agents/skills"
-ln -s "$CODEX_HOME/lumen/skills" "$HOME/.agents/skills/lumen"
-codex mcp add lumen -- "$CODEX_HOME/lumen/scripts/run" stdio
-```
+[.codex/INSTALL.md](.codex/INSTALL.md)
 
-Detailed docs: [.codex/INSTALL.md](.codex/INSTALL.md)
+The installer enables Codex hooks, registers the Lumen MCP server, links or
+copies the shared Lumen skills, and installs a user-level Codex `SessionStart`
+hook. The hook runs on startup, resume, and clear events and reuses Lumen's
+background indexer for proactive project index warmup.
 
 Verify with:
 
 ```bash
+"${CODEX_HOME:-$HOME/.codex}/lumen/scripts/run" codex doctor
 codex mcp get lumen
-ls -la "$HOME/.agents/skills/lumen"
 ```
 
 **OpenCode**
@@ -161,7 +153,8 @@ opencode mcp list
 - **Claude Code** - update through Claude's plugin marketplace
 - **Cursor** - refresh or reinstall the bundled plugin through Cursor after
   updating this repository or the published package
-- **Codex** - `cd "${CODEX_HOME:-$HOME/.codex}/lumen" && git pull`
+- **Codex** - `cd "${CODEX_HOME:-$HOME/.codex}/lumen" && git pull`, then
+  rerun `./scripts/run codex install`
 - **OpenCode** - update the version pin in `opencode.json` (e.g.
   `@ory/lumen-opencode@0.0.29`) and restart OpenCode
 
@@ -172,8 +165,9 @@ On first Claude Code or Cursor session start, Lumen:
 2. Indexes your project in the background using Merkle tree change detection
 3. Registers a `semantic_search` MCP tool that the host can use automatically
 
-In Codex and OpenCode, the same binary download and index seeding happen on the
-first `semantic_search` call.
+In Codex, the installed `SessionStart` hook warms the index on startup, resume,
+and clear events. In OpenCode, index seeding happens on the first
+`semantic_search` call.
 
 Two shared skills are also available: `doctor` (health check) and `reindex`
 (forced re-indexing). Claude exposes them as `/lumen:doctor` and