Codex solves this through a collection of repository-aware configuration surfaces:
AGENTS.md
.codex/config.toml
.agents/skills/*/SKILL.md
.codex/agents/*.toml
MCP server configuration
These are sometimes compared with Claude Code’s CLAUDE.md, .claude/settings.json, command files, agent files and .mcp.json. The concepts overlap, but the files are not interchangeable. Codex has its own discovery rules and nomenclature.
A practical translation looks like this:
+----------------------+-------------------------+------------------------------+
| Claude convention | Codex equivalent | Purpose |
+----------------------+-------------------------+------------------------------+
| CLAUDE.md | AGENTS.md | Persistent repositoryguidance|
+----------------------+-------------------------+------------------------------+
| .claude/settings.json|.codex/config.toml | Projectconfiguration |
+----------------------+-------------------------+------------------------------+
| .claude/commands/*.md|.agents/skills/*/SKILL.md| Reusableworkflows |
+----------------------+-------------------------+------------------------------+
| .claude/agents/*.md |.codex/agents/*.toml | Customsubagent roles |
+----------------------+-------------------------+------------------------------+
| Project .mcp.json | MCP tablesin | External tools andcontext |
| |.codex/config.toml | |
+----------------------+-------------------------+------------------------------+
| Distributable package| Codexplugin | Bundle skills,MCP, hooks and |
| | |connectors |
+----------------------+-------------------------+------------------------------+
Let us examine how these pieces work—and how to manage them across a serious multi-team GitHub organization.
AGENTS.md: the repository’s operating manual
AGENTS.md contains durable instructions Codex should follow whenever it works in a repository.
It should not explain everything about the product. It should tell Codex how to operate safely and effectively inside the codebase.
Typical contents include:
·Build, test and lint commands
·Repository structure
·Architectural boundaries
·Code-generation rules
·Definition of done
·Pull-request expectations
·Security-sensitive areas
·Instructions for database migrations
·Whereto find authoritative documentation
·Which team owns which subsystem
Codex reads these files before beginning work. It constructs an instruction chain once per run, beginning with personal guidance and continuing from the repository root toward the current working directory. Instructions closer to the working directory take precedence. The default combined project-instruction limit is 32KiB.
That enables a layered monorepo:
commerce-platform/
├── AGENTS.md
├── apps/
│ ├── storefront/
│ │ └── AGENTS.md
│ └── operations-console/
│ └── AGENTS.md
├── services/
│ ├── catalogue/
│ │ └── AGENTS.md
│ ├── checkout/
│ │ └── AGENTS.md
│ └── payments/
│ └── AGENTS.override.md
└── packages/
├── design-system/
│ └── AGENTS.md
└── observability/
└── AGENTS.md
The root file contains rules shared by every team:
# Repository operating instructions
## Navigation
- `apps/` contains user-facing applications.
- `services/` contains independently deployable backend services.
- `packages/` contains shared libraries.
- Read the nearest nested `AGENTS.md` before modifying a component.
## Validation
- Run `pnpm lint` for formatting and static checks.
- Run `pnpm test --filter <workspace>` for affected packages.
- Run `pnpm typecheck` before declaring implementation complete.
- Do not run the entire integration suite locally unless requested.
## Architecture
- Applications may depend on packages, but packages must not depend on apps.
- Services communicate through versioned APIs or events.
- Do not import another service's internal modules.
- Generated API clients must be updated from the source schema.
## GitHub workflow
- Keep pull requests focused on one operational change.
- Link the relevant GitHub issue.
- Include testing evidence and rollout risk in the PR description.
- Do not push directly to `main`.
The payment team can then add local requirements:
# Payments-specific instructions
## Required checks
- Run `make test-payments`.
- Run `make verify-contracts` after changing a payment event.
- Add or update idempotency tests for every write operation.
## Safety
- Never log PAN, CVV, secrets or complete payment tokens.
- Do not modify settlement logic and database schemas in the same PR.
- Migrations must be backward-compatible with the currently deployed release.
## Ownership
- Request review from `@acme/payments-platform`.
- Escalate changes affecting tokenization to `@acme/security`.
An AGENTS.override.md replaces the ordinary AGENTS.md at the same directory level. It is useful for exceptional environments or temporary migration rules, but ordinary nested AGENTS.md files are usually easier to maintain.
The key principle is locality:
GLOBAL RULES
│
▼
REPOSITORY RULES
│
▼
DOMAIN RULES
│
▼
SERVICE-SPECIFIC RULES
Do not put 400lines of payments guidance in the root file. It wastes context for every team and increases the probability of conflicting instructions.
.codex/config.toml: project behavior and permissions
If AGENTS.md explains how Codex should work, .codex/config.toml controls the environment in which it works.
Codex supports:
·Personal configuration in ~/.codex/config.toml
·Project configuration in .codex/config.toml
·Nested project configuration for subdirectories
·Profiles and system-level configuration
·Command-line overrides
Project configuration is loaded only for trusted projects. The CLI and IDE extension share these configuration layers. Settings closer to the current working directory take precedence over broader project settings.
A conservative project configuration might resemble:
approval_policy ="on-request"
sandbox_mode = "workspace-write"
[agents]
max_concurrent_threads_per_session = 6
[mcp_servers.github]
url = "https://github.example.com/mcp"
default_tools_approval_mode = "writes"
enabled_tools = [
"search_code",
"read_pull_request",
"list_check_runs",
"create_pull_request_comment"
]
Configuration belongs here when it concerns capabilities, permissions or runtime behavior.Instructions belong in AGENTS.md when they concern engineering judgment.
"Run the service testsuite" → AGENTS.md
"The test command is make test-api" → AGENTS.md
"Use a workspace-write sandbox" → .codex/config.toml
"Prompt before tools write to GitHub" → .codex/config.toml
Do not commit secrets, personal access tokens or production credentials. Store secrets in an approved secret manager or environment variable and refer to the variable from configuration.
In enterprise environments, administrators can also impose requirements that project configuration cannot override. Repository teams propose useful defaults, while security and platform teams retain policy control.
Skills:the Codex replacement for project command files
A command fileu sually represents a procedure: prepare a release, investigate an incident, create a migration or review a pull request.
In Codex, the natural representation is a skill.
A skill is a directory containing a required SKILL.md plusoptional scripts, references and assets:
.agents/
└── skills/
├── prepare-release/
│ ├── SKILL.md
│ ├── scripts/
│ │ └── verify-release.sh
│ └── references/
│ └── release-policy.md
├── review-api-change/
│ └── SKILL.md
└── investigate-production-incident/
├── SKILL.md
└── references/
└── severity-model.md
SKILL.md begins with metadata:
---
name: review-api-change
description: Review REST, GraphQL or event-contract changes for
compatibility, ownership, rollout risk and missing consumer tests.
---
# API change review
1. Identify the authoritative schema and owning team.
2. Compare the branch against the merge base.
3. Classify changes as additive, behavioral or breaking.
4. Find known consumers through code search and the GitHub dependency graph.
5. Verify contract tests and generated clients.
6. Report compatibility risks, affected consumers, required migration
sequence, missing tests and recommended reviewers.
Do not modify code unless explicitly asked.
Codex initially sees the skill’s name and description. It reads the complete instructions only when the skill is selected, a process OpenAI calls progressive disclosure.Codex may choose a skill automatically when a task matches its description, ora developer can invoke it explicitly by mentioning $review-api-change. In the CLI and IDE, /skills displays available skills.
Important distinction: this differs from registering arbitrary project slash commands. Codex slash commands primarily control the Codex interface; reusable team procedures belong in skills.
For large organizations, useful skills include:
·$prepare-release
·$review-database-migration
·$trace-cross-service-request
·$create-architecture-decision
·$investigate-ci-failure
·$review-api-compatibility
·$perform-threat-model
·$generate-service-runbook
·$triage-dependency-update
Skills should encode a repeatable process, not merely a prompt fragment. If a workflow can be checked mechanically, include a script. If it depends on policy, include the authoritative reference. If it needs GitHub, Jira, logs or documentation, pair it with MCP.
Custom agents: specialists with bounded responsibilities
Skills tellCodex how to perform a workflow. Custom agents define specialist roles to whichCodex can delegate part of a larger task.
Project-scoped custom agents use standalone TOML files in .codex/agents/. Personal agents live in ~/.codex/agents/.
.codex/
├── config.toml
└── agents/
├── code-mapper.toml
├── security-reviewer.toml
├── test-strategist.toml
└── github-coordinator.toml
Each file requires a name, description and developer_instructions. It can also set a model, reasoning effort, sandbox mode, skills and MCP servers.
name ="security_reviewer"
description = "Read-only reviewer for authentication, authorization,
secrets, input handling and sensitive-data risks."
sandbox_mode = "read-only"
model_reasoning_effort = "high"
developer_instructions = """
Review only security-relevant behavior.
Trace trust boundaries and concrete data flows before reporting a concern.
Prioritize exploitable findings over theoretical hardening.
Include file and symbol evidence.
Do not modify code.
Recommend the smallest safe remediation and relevant regression tests.
"""
A coordinated pull-request review might look like this:
┌──────────────────┐
│ PRIMARY CODEX │
│ coordinates work │
└────────┬─────────┘
│
┌──────────────────┼──────────────────┐
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐┌─────────────────┐
│ code_mapper │ │security_reviewer││ test_strategist │
│ traces impact │ │ checks risks ││ finds test gaps │
└────────┬────────┘ └───────┬─────────┘└────────┬────────┘
└──────────────────┬───────────────────┘
▼
┌──────────────────┐
│ ConsolidatedPR │
│ review with │
│ rankedfindings │
└──────────────────┘
The best agents are narrow. Avoid agents called backend-expertor helpful-reviewer. Prefer roles with explicit outputs and boundaries.
Subagents are especially valuable when work can be divided independently: mapping an unfamiliar code path, checking documentation, examining test coverage or reviewing security. They are less useful when several agents would edit the same files simultaneously.
MCP:connecting Codex to the engineering organization
A repository contains code, but large-project context lives elsewhere:
·GitHub issues and pull requests
·CI results
·Architecture documentation
·Incident-management systems
·Service catalogues
·Observability platforms
·Designsystems
·Deployment environments
Model ContextProtocol connects Codex to these systems.
Unlike Claude projects that may detect a root .mcp.json,normal Codex project MCP configuration belongs in .codex/config.toml:
[mcp_servers.github]
url = "https://github.example.com/mcp"
default_tools_approval_mode = "writes"
[mcp_servers.service_catalog]
url = "https://catalogue.example.internal/mcp"
default_tools_approval_mode = "prompt"
[mcp_servers.observability]
command = "company-observability-mcp"
args = ["--environment", "staging"]
enabled_tools = ["search_logs", "read_trace","list_alerts"]
The desktop app,CLI and IDE extension share Codex MCP configuration, so engineers do not need separate setup for every interface.
Treat every MCP server as a capability boundary. Reading an issue is different from merging a pull request. Searching staging logs is different from restarting production.
Read tools → automatic or low-friction approval
Comment/create operations → prompt or writes-only approval
Deploy/delete operations → explicit approval
Production access → centrally managed and narrowly scoped
DistributingCodex configuration across repositories
There are two legitimate distribution models.
Repository-native configuration
Commit project-specific files directly into each repository:
repo/
├── AGENTS.md
├── .codex/
│ ├── config.toml
│ └── agents/
├── .agents/
│ └── skills/
└── .github/
├── CODEOWNERS
└── workflows/
This is best for build commands, architectural rules, service-specific workflows and ownership information.
Plugins for organization-wide capabilities
When a workflow must be reused across many repositories, package it as a Codex plugin. Plugin scan bundle skills, hooks, MCP definitions, connectors and assets behind a required .codex-plugin/plugin.json manifest. Repository-scoped plugin catalogues can be published through .agents/plugins/marketplace.json.
engineering-codex-plugin/
├── .codex-plugin/
│ └── plugin.json
├── skills/
│ ├── incident-response/
│ ├── api-review/
│ └── release-governance/
├── hooks/
│ └── hooks.json
└── .mcp.json
That plugin-level .mcp.json is the notable exception: it is referenced by the plugin manifest and distributed as part of the plugin. A random .mcp.json dropped into an ordinary Codex project is not a replacement for project MCP configuration.
A healthy enterprise model is therefore:
Central plugin
├── shared release process
├── security-review workflow
├── organization MCP integrations
└── common engineering policy
Each repository
├── local AGENTS.md
├── service-specific skills
├── project config
└── custom ownership rules
Do not force every repository to copy an enormous central AGENTS.md. Centralize reusable machinery; keep contextual instructions close to the code.
Governing the files through GitHub
These files change agent behavior and deserve ordinary engineering governance.
Assign owners:
# .github/CODEOWNERS
/AGENTS.md @acme/platform-engineering
/.codex/ @acme/developer-experience @acme/security
/.agents/skills/ @acme/developer-experience
/services/payments/AGENTS.md @acme/payments-platform
GitHub automatically requests designated code owners when a pull request changes their files, and protected branches can require code-owner approval.
Add required checks that:
·Parse every TOML file
·Validate skill frontmatter
·Reject broken internal links
·Detect references to nonexistent commands
·Search for committed secrets
·Confirm required owners exist
·Run example commands in a safe test environment
·Report divergence from centrally maintained templates
GitHub ruleset scan require these checks before merging and can require pull requests, code scanning, signed commits and code-owner review.
Finally, treat guidance as a feedback system. If reviewers repeatedly tell Codex not to edit a generated file, encode that locally. If Codex keeps running the wrong test suite, correct the nearest AGENTS.md. If five repositories need the same release workflow, promote it into a shared skill or plugin.
That is the real value of Codex configuration. It does not merely give an AI more context. It converts accumulated review feedback, operational knowledge and team boundaries into a versioned engineering interface:
Human correction
│
▼
AGENTS.md / skill / agent
│
▼
Future Codex sessions
│
▼
More consistent changes
│
▼
GitHub review and CI
│
└──────────────► next correction
The result is not an autonomous software factory. It is something more useful: an agent that enters each team’s part of the codebase already knowing the local roads, speed limits and definition of safe arrival.
