install-codex-config

# Install Codex Config ## Contents - Source discovery - Components - Inventory - User confirmation - Install rules - Post-install Use this skill to install or update the checked-in Codex configuration on the current machine. Use only files from the local repository. Do not fetch configuration from GitHub or any other network source. ## Source discovery 1. Determine the git root with `git rev-parse --show-toplevel` when available. 2. Choose the source root: - Prefer `<git-root>/codex-config` when it contains `config.toml` and `global-agents.md`. - Otherwise use `<git-root>` when it contains `config.toml` and `global-agents.md`. This is the expected layout after extracting `codex-config/` into its own repository. - If neither layout is found, inspect the current directory and its parents for the same two-file marker. 3. Confirm source files exist before offering them as installable components. ## Components Offer these components to the user. Mark missing target components as recommended, but still let the user choose. - **AGENTS.md**: compact cross-task working agreements for Codex sessions. - Source: `<source-root>/global-agents.md` - Target: `~/.codex/AGENTS.md` - **config.toml**: model defaults, permissions, hooks, TUI status line, analytics, history, and feature flags. - Source: `<source-root>/config.toml` - Target: `~/.codex/config.toml` - **MCP servers**: Context7 and Exa server entries. - Source: `<source-root>/mcp-template.toml` - Target: merge into `~/.codex/config.toml` - **Profile template** (optional): auth-identity profile for `--profile`. Do not install it by default; offer it only if the user wants a second identity, such as an API-key login alongside a ChatGPT-plan login. - Source: `<source-root>/profile-template.toml` - Target: copy to `~/.codex/<name>.config.toml` using the user's name or `api` by default. - **Hooks**: command policy, package manager enforcement, and GAM mutation logging. - Source: `<source-root>/hooks/*.sh` - Target: `~/.codex/hooks/*.sh` - **Rules**: command approval policy examples. - Source: `<source-root>/rules/default.rules` - Target: `~/.codex/rules/default.rules` - **Skills**: reusable Codex workflows, including project-aware development configuration examples. - Discover sources with `<source-root>/scripts/list_skills.py <source-root>`. - Each reported `.../<name>/SKILL.md` maps to `~/.agents/skills/<name>/SKILL.md`; copy its complete skill directory. ## Inventory Read or check these fixed target paths: - `~/.codex/AGENTS.md` - `~/.codex/config.toml` - `~/.codex/hooks/block-dangerous-command.sh` - `~/.codex/hooks/enforce-package-manager.sh` - `~/.codex/hooks/log-gam.sh` - `~/.codex/rules/default.rules` Run the skill discovery script and check the corresponding `~/.agents/skills/<name>/SKILL.md` target for every result. Do not maintain a hard-coded skill inventory in this workflow. Also inspect `~/.codex/config.toml` for existing `[mcp_servers.context7]` and `[mcp_servers.exa]` tables. If the user asks about the optional profile template, check for existing `~/.codex/*.config.toml` profile files before writing one. ## User confirmation Before writing outside the repository, present a concise install plan: - selected components; - source root; - target paths; and - overwrite or merge behavior for existing files. Ask for confirmation. If the environment supports a structured selection UI, use it. Otherwise ask a single concise question and accept a comma-separated list such as `agents, config, mcp, hooks, rules, skills, all`. ## Install rules ### AGENTS.md If `~/.codex/AGENTS.md` is missing, install `global-agents.md` from the source root. If it exists, show the user a diff or concise summary and ask whether to overwrite, skip, or merge manually. Do not silently overwrite it. ### config.toml If `~/.codex/config.toml` is missing, install the source file. If it exists, merge conservatively: - Preserve user keys that are not present in the source template. - Prefer the source template for organization-standard keys when the user selected a config update. - Preserve authentication, trust, and local provider/model overrides unless the user explicitly asks to replace them. - Show the merged TOML before writing. After writing, validate TOML syntax. ### MCP servers Merge only missing `[mcp_servers.context7]` and `[mcp_servers.exa]` tables from `mcp-template.toml` into `~/.codex/config.toml`. Do not duplicate existing MCP server entries. Remind the user that Exa needs `EXA_API_KEY` available in the environment or credential management layer. ### Profile template Only install this component when the user opts in. Ask for a profile name, defaulting to `api`, and copy `profile-template.toml` to `~/.codex/<name>.config.toml`. Do not overwrite an existing profile of that name without confirmation. Remind the user to create the key file the profile reads; the template uses `~/.codex/api-key.txt`. Never commit API keys. If the user chose a non-default name, update the `api-key.txt` path in the copied profile's `auth.command` to match. Select the profile at runtime with `codex --profile <name>`; do not merge it into `config.toml`. ### Hooks Create `~/.codex/hooks/` if needed. Copy selected hook scripts from the source root and set executable bits. Existing hook files may be overwritten after the user confirms the hooks component. ### Rules Create `~/.codex/rules/` if needed. Copy `default.rules`. If the target exists, ask whether to overwrite or skip unless the user selected a full refresh. ### Skills Run the discovery script immediately before preview and again immediately before installation. Create `~/.agents/skills/` if needed. For every reported entrypoint, copy its complete parent skill directory to the same directory name under the target. Existing discovered skill directories may be overwritten after the user confirms the skills component. Do not delete or change target skill directories that are absent from the source repository. When installing skills globally, install every discovered skill, including this one. Preserve unrelated user-local skill directories. ## Post-install Summarize: - files installed; - files merged; - files skipped; - validation run; and - follow-up needed for `EXA_API_KEY` or platform-specific keyring behavior. If `config.toml` changed, suggest starting a fresh Codex session so the new defaults, hooks, skills, and MCP entries are loaded.