Codex automatically discovers a limited set of files:
| Purpose | User scope | Repository scope |
|---|---|---|
| Instructions | ~/.codex/AGENTS.md |
AGENTS.md from the repository root to the working directory |
| Configuration | ~/.codex/config.toml |
.codex/config.toml in trusted projects |
| Skills | ~/.agents/skills/ |
.agents/skills/ from the working directory to the repository root |
| Rules | ~/.codex/rules/ |
Project rules next to an active trusted .codex/config.toml layer |
Codex does not recursively read arbitrary files under docs/. A loaded
AGENTS.md, selected skill, or user prompt must point Codex to the relevant
document.
The active ~/.codex directory mixes portable configuration with private and
ephemeral runtime state. Examples include:
auth.json- installation identifiers
- session transcripts and history
- SQLite state and write-ahead logs
- model and application caches
- downloaded plugins
- shell snapshots
Tracking or replacing those files would expose credentials, create noisy changes, and make the setup less portable.
This repository manages only:
- global instructions
- user configuration defaults
- optional local model profiles
- command rules
- reusable skills
- an opt-in list of recommended plugin selectors
The installer links instructions, rules, profiles, and skills into their
documented locations while preserving runtime state. If config.toml is
absent, it creates a regular file with defaults and machine-specific trust
entries. Existing config files and links to files are preserved without
parsing or merging them. Personal model choices, MCP servers, trust decisions,
and app state remain intact. See setup and customization for updates.
With the explicit plugin option, it asks Codex to install each selector from
codex-plugins.txt; it does not link or track the resulting plugin cache,
authentication, or connector state.
Codex project trust uses exact absolute project paths. A parent project entry
and wildcard entries do not automatically trust nested repositories. When no config exists, the installer adds the current user's ~/github path plus every Git
worktree found recursively below it to the generated config. Existing configs are unchanged on subsequent installs. Manage new
project trust in Codex or your installed config.
Run the installer with --plugins on Linux or macOS, or -Plugins on Windows,
to install the selectors in codex-plugins.txt. Without that option, plugin
state is untouched. Restart Codex or start a new session after installing a
plugin so its bundled skills and tools can load.
Plugins can package skills, connectors, MCP servers, hooks, and other assets. Standalone services such as Context7, Playwright, and Chrome DevTools are MCP servers, not entries managed by this repository's plugin manifest. Configure those separately when a project needs them.
PhotoCraft is enabled in the managed default configuration for CLI and desktop
sessions. Install photocraft-cli separately, run the installer for profile and skill links, and restart Codex from the artwork directory.
For an existing config, add the [mcp_servers.photocraft] section from
codex-home/config.toml yourself if missing. The server uses that startup directory as its read/write roots. The optional
photocraft.config.toml profile makes server startup required; default sessions
can still start on machines without the binary. See PhotoCraft MCP.
Codex profile files live directly under CODEX_HOME and use the name
<profile>.config.toml.
This repository includes:
ollama.config.tomlfor Codex's built-in Ollama provider.llamacpp.config.tomlfor a local llama.cpp Responses API endpoint.
Profiles layer over config.toml only when selected with --profile, so local
model settings do not affect ordinary Codex sessions.
Older local layouts may place skills under .codex/skills. Current Codex
documentation uses .agents/skills for user and repository skills. This
repository uses .agents/skills as its canonical location.
Do not point CODEX_HOME at this repository. Codex writes runtime state into
CODEX_HOME, while this repository intentionally separates managed files from
runtime data. Use scripts/install.sh on Linux or macOS and
scripts/install.ps1 on Windows instead.
After installation, restart Codex and ask:
List the instruction sources and relevant skills active for this repository.
The expected instruction order is:
~/.codex/AGENTS.md- the repository root
AGENTS.md - any closer nested
AGENTS.mdorAGENTS.override.md