feat(codex): Add first-class Codex support

[reneleonhardt]

What does this PR do?

• Add first-class Codex project setup, hooks, MCP configuration, plugin installation, upgrades, and diagnostics without replacing Claude integration.
• Use absolute, versioned executable paths so managed integrations do not depend on a restricted host PATH.
• Validate Codex hook trust and distinguish CLI and Desktop runtimes independently.
• Make setup and plugin installation idempotent while preserving unrelated user configuration.
• Allow hooks-only setup with --no-mcp when the Codex plugin owns MCP.
• Document the one-time plugin-first setup order and per-project upgrade refresh workflow.
• Unify codemap mcp and codemap-mcp option parsing and server behavior.

Type of change

• Bug fix
• New feature
• New language support
• Documentation
• Other (describe below)

Checklist

• I've tested this locally with go build && ./codemap .
• I've read CONTRIBUTING.md (for new language support)
• I've updated documentation if needed

Additional notes

Codemap was Claude-first. Codex integrations could fail because of restricted host PATHs, stale project overrides, untrusted hooks, and unclear plugin upgrades. This change lets both agents operate independently or together without overwriting existing configuration.

The final MCP commit routes both executable entrypoints through the same runtime-option parser and server constructor. A black-box parity test compares option errors, tool discovery, status guidance, and file-search responses.

Formatting, modules, vet, staticcheck, focused and race tests, debug smoke,
entrypoint parity, repeated plugin/setup, and CLI-less doctor validation pass.

Reviewer setup:

set -euo pipefail

ROOT=$PWD
BRANCH=feat/codex-first-class
REVIEW_ROOT=$(mktemp -d "${TMPDIR:-/tmp}/codemap-codex-review.XXXXXX")
WT="$REVIEW_ROOT/worktree"
DEBUG_BIN="$REVIEW_ROOT/codemap-debug"
COVERAGE_OUT="$REVIEW_ROOT/coverage.out"

cleanup() {
  cd "$ROOT"
  git worktree remove --force "$WT"
  rm -rf "$REVIEW_ROOT"
}
trap cleanup EXIT

git worktree add --detach "$WT" "$BRANCH"
cd "$WT"
go fmt ./...
git diff --exit-code
go mod verify
go vet ./...
staticcheck ./...
go test . ./cmd ./mcp ./plugins ./internal/buildinfo -count=1
go test -race -coverprofile="$COVERAGE_OUT" ./...
go build -gcflags='all=-N -l' -o "$DEBUG_BIN" .
"$DEBUG_BIN" --version
"$DEBUG_BIN" .

REVIEW_HOME="$REVIEW_ROOT/home"
PROJECT="$REVIEW_ROOT/project"
NO_AGENT_PATH="$REVIEW_ROOT/no-agent-bin"
mkdir -p "$REVIEW_HOME" "$PROJECT/.git" "$NO_AGENT_PATH"
printf 'package main\n' > "$PROJECT/main.go"

HOME="$REVIEW_HOME" "$DEBUG_BIN" plugin install --home "$REVIEW_HOME" --no-activate
HOME="$REVIEW_HOME" "$DEBUG_BIN" plugin install --home "$REVIEW_HOME" --no-activate
HOME="$REVIEW_HOME" PATH="$NO_AGENT_PATH" "$DEBUG_BIN" setup --agent codex "$PROJECT"
HOME="$REVIEW_HOME" PATH="$NO_AGENT_PATH" "$DEBUG_BIN" setup --agent codex "$PROJECT"
HOME="$REVIEW_HOME" PATH="$NO_AGENT_PATH" "$DEBUG_BIN" doctor "$PROJECT"
cleanup
trap - EXIT

To test the live MCP integration, run Codex against the generated project, trust the hooks from /hooks in CLI or Settings > Hooks in Desktop, and start a new task. The generated project configuration already points to the exact debug binary.

Developed with carefully directed, manually reviewed AI assistance. Allow edits by maintainers is enabled, so maintainers are welcome to fix wording or make minor cleanup directly; broader review feedback will be incorporated.

Co-Authored-By: GPT-5.6 Sol codex@openai.com