| 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
- Determine the git root with
git rev-parse --show-toplevel when available.
- 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.
- 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.
