AGENTS.md

1# src/cli/install-codex/ — Codex Light Edition Installer (39 Files)
2 
3**Generated:** 2026-06-06
4 
5## OVERVIEW
6 
7Installs the `omo` plugin into `~/.codex/` for the Codex CLI Light edition. This directory is now an OpenCode CLI adapter shim over the canonical installer source in [`packages/omo-codex/src/install/`](../../../../../packages/omo-codex/src/install). Entry: `runCodexInstaller()` in `install-codex.ts`. Triggered by `bunx oh-my-openagent install --platform=codex` (alias `npx lazycodex-ai install`).
8 
9## KEY FILES
10 
11| File | Purpose |
12|------|---------|
13| `install-codex.ts` | Main orchestrator `runCodexInstaller()` — resolves paths, loops over marketplace plugins, drives cache/install/config phases |
14| `types.ts` | `CodexInstallOptions`, `CodexInstallResult`, `MarketplaceManifest`, `PluginManifest`, `InstalledPlugin` |
15| `codex-marketplace.ts` | Reads `packages/omo-codex/marketplace.json` and per-plugin `.codex-plugin/plugin.json`; validates path segments |
16| `codex-cache-install.ts` | Builds source, copies to temp cache dir, runs `npm ci --omit=dev`, rewrites MCP manifest, atomically promotes to `~/.codex/plugins/cache/{marketplace}/{name}/{version}/` |
17| `codex-cache-bins.ts` | Discovers `package.json` `bin` entries, links component CLIs into bin dir; writes `omo` runtime wrapper (POSIX shell / Windows `.cmd`) |
18| `link-cached-plugin-agents.ts` | Discovers bundled agent TOMLs under `components/*/agents/`, copies to `~/.codex/agents/`, preserves existing `model_reasoning_effort` and `service_tier`, writes `.installed-agents.json` manifest |
19| `codex-marketplace-snapshot.ts` | Writes local marketplace snapshot to `~/.codex/.tmp/marketplaces/{marketplace}/` |
20| `codex-config-toml.ts` | Mutates `~/.codex/config.toml`: enables features, sets marketplace/plugin/agent/hook-trust blocks, optional autonomous permissions |
21| `codex-cleanup.ts` | Uninstall orchestrator: removes cache, agents, config blocks, project-local artifacts |
22 
23## INSTALL FLOW
24 
25```
26runCodexInstaller()
27  1. resolve repoRoot / codexHome / binDir / projectDirectory
28  2. git-bash.ts: Windows Git Bash preflight (discovery-first; no automatic winget/system install)
29  3. codex-marketplace.ts: read marketplace.json + plugin manifests
30  4. lazycodex-version-stamp.ts: resolve plugin version from distribution manifest
31  5. For each marketplace plugin:
32     a. codex-cache-install.ts: build, copy, npm ci, rewrite MCP manifest, promote to cache
33     b. codex-cache-bins.ts: link component CLIs + omo runtime wrapper
34     c. link-cached-plugin-agents.ts: copy agent TOMLs to ~/.codex/agents/
35  6. codex-cache-prune.ts: remove stale plugins + legacy marketplace caches
36  7. codex-config-toml.ts: mutate ~/.codex/config.toml
37  8. codex-project-local-cleanup-best-effort.ts: repair project-local .codex/config.toml conflicts
38  9. Telemetry: track install_completed
39```
40 
41## WHAT IT WRITES
42 
43| Path | What |
44|------|------|
45| `~/.codex/plugins/cache/{marketplace}/{plugin}/{version}/` | Built plugin cache (npm installed, MCP manifest rewritten) |
46| `~/.codex/.tmp/marketplaces/{marketplace}/` | Local marketplace snapshot (copied plugin sources + `marketplace.json`) |
47| `~/.codex/agents/*.toml` | Copied agent configurations from bundled components |
48| `~/.codex/config.toml` | Mutated with marketplace block, plugin enablement, feature flags, agent configs, hook trust hashes, MCP policies |
49| `~/.local/bin/` (or `~/.codex/bin` if custom home) | Symlinks or `.cmd` shims for component CLIs + `omo` wrapper |
50 
51## CONVENTIONS
52 
53- All TOML mutation is string-based via `toml-section-editor.ts` (no TOML parser dependency)
54- Atomic directory promotion: copy to temp sibling, then `rename()`; backup restored on failure
55- Windows uses `.cmd` shims; POSIX uses symlinks
56- Current managed Codex agent roster: `explorer`, `librarian`, `metis`, `momus`, `plan`
57- Legacy purge/back-compat code still tracks the retired reviewer agent so installs can remove stale config and agent files from older releases
58- Legacy marketplace cleanup: `lazycodex` and `code-yeongyu-codex-plugins` are pruned on `sisyphuslabs` install
59 
60## ANTI-PATTERNS
61 
62- Never use a real TOML parser for config edits; the text-manipulation layer is intentional to avoid dependencies
63- Never skip the temp-and-rename promotion in cache install; direct writes risk corrupting a live cache
64- Never hardcode new agent names without updating `MANAGED_CODEX_AGENT_NAMES` in both `codex-config-agents.ts` and `codex-cleanup-config.ts`
65