install-codex-config

name	install-codex-config
description	Install or update this organization's Codex configuration from repo-local files into the user's Codex home. Use when asked to set up, install, update, bootstrap, or sync this Codex configuration, including the global AGENTS template, config.toml, hooks, rules, MCP servers, profile templates, and bundled skills.

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.