OpenAI Codex AGENTS.md Complete Guide — Custom Configuration & MCP Integration for Maximum Efficiency [2026]

AGENTS.md is a Markdown file you place in your repository to give Codex persistent, project-specific instructions. Think of it as a README for your AI agent — while a README explains the project to humans, AGENTS.md explains it to Codex. With a well-crafted AGENTS.md, you never have to repeat "use TypeScript strict mode," "run tests with pnpm test," or "follow Conventional Commits" in every chat. Codex reads AGENTS.md at the start of each task, absorbs your project context, and proceeds accordingly. The result: fewer misunderstandings, fewer correction loops, and higher-quality outputs from the first attempt.

Codex searches multiple locations for AGENTS.md and merges instructions according to a strict priority order: ``` [Highest priority] AGENTS.override.md (subdirectory) ↓ AGENTS.md (subdirectory) ↓ Traverse parent directories up to git root ↓ ~/.codex/AGENTS.md (global config) ↓ [Lowest priority] Fallback (TEAM_GUIDE.md / CONTRIBUTING.md etc.) ``` Practical patterns: - Repo root `AGENTS.md`: project-wide conventions - Subdirectory (e.g., `frontend/AGENTS.md`): frontend-specific overrides - `~/.codex/AGENTS.md`: personal preferences and global settings - `AGENTS.override.md`: emergency overrides for urgent situations

Here is a battle-tested AGENTS.md template you can adapt for your project: ```markdown # AGENTS.md — Project: my-saas-app ## Codebase Structure - `src/app/` — Next.js App Router (pages & layouts) - `src/components/` — Reusable UI components - `src/lib/` — Utilities, DB, validation - `api/` — Backend API routes - `tests/` — Vitest test files ## Environment - Node.js 22.x - Package manager: pnpm (never use npm) - Test framework: Vitest ## Commands - Dev server: `pnpm dev` - Tests: `pnpm test --run` (no watch mode) - Build: `pnpm build` - Lint: `pnpm lint` ## Coding Conventions - TypeScript strict mode is mandatory - Follow ESLint + Prettier configuration - Functional components only (no class components) - Custom hooks must use the `use` prefix ## Git & PR Conventions - Conventional Commits: `feat:`, `fix:`, `chore:`, `docs:` - Branch naming: `feat/issue-123-feature-name` - Every PR must include tests ## Security (Non-Negotiable) - NEVER read or write `.env`, `.env.local`, or `credentials/` - NEVER hardcode API keys or secrets in source code - NEVER log sensitive data with `console.log` ## Forbidden - Generating `package-lock.json` (pnpm only) - Using the `any` type (maintain type safety) - Leaving `// TODO` comments in a PR ```

Alongside AGENTS.md, `.codex/config.toml` enables more detailed behavioral configuration: ```toml # .codex/config.toml [agent] # Commands to run before every task setup_commands = ["pnpm install", "pnpm build:types"] # Verification commands after task completion verify_commands = ["pnpm lint", "pnpm test --run"] # Files Codex can access include_patterns = ["src/", "api/", "tests/**"] # Excluded files (security) exclude_patterns = [".env*", "credentials/**", "*.pem"] [sandbox] memory_limit = 4096 # MB timeout = 1800 # seconds [pr] default_labels = ["ai-generated", "needs-review"] default_reviewers = ["@team-lead"] ```

Model Context Protocol (MCP) enables Codex to connect with Figma, Linear, Jira, GitHub, and your internal wiki. MCP configuration example (`~/.codex/mcp.json`) ```json { "servers": [ { "name": "github", "type": "stdio", "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] }, { "name": "linear", "type": "stdio", "command": "npx", "args": ["-y", "@linear/mcp-server"], "env": { "LINEAR_API_KEY": "${LINEAR_API_KEY}" } }, { "name": "figma", "type": "sse", "url": "https://figma.com/mcp/sse" } ] } ```

In March 2026, Codex introduced a plugin ecosystem built around reusable task templates called Skills. Skills definition example (`.codex/skills/add-test.yaml`) ```yaml name: add-unit-test description: Automatically generate unit tests for a specified file parameters: - name: target_file type: string description: Path to the file to be tested prompt: | Create Vitest unit tests for {{target_file}}. - Cover all exported functions - Include edge cases (null, undefined, empty arrays) - Place tests in the tests/ directory - Match the existing test style ``` Invoke it with: `codex run skill add-unit-test --target_file src/lib/utils.ts` Teams can share Skills as npm packages, and an open-source ecosystem of standardized Skills is rapidly growing.

Codex exposes `SessionStart`, `SessionStop`, and `userpromptsubmit` hook points for workflow automation. Hook configuration example (`.codex/hooks.toml`) ```toml [hooks.session_start] command = "pnpm install --frozen-lockfile" timeout = 60 [hooks.session_stop] command = "pnpm store prune" [hooks.before_commit] command = "pnpm lint && pnpm test --run" fail_on_error = true ``` Hook execution flow: ``` [Task received] ↓ SessionStart Hook → Environment init, dependency update ↓ [Codex working] ↓ userpromptsubmit Hook → Input validation, logging ↓ [Task complete] ↓ before_commit Hook → Lint + test verification ↓ SessionStop Hook → Cleanup ```

The full power of Codex emerges when combined with GitHub Actions. Here is a workflow that automatically dispatches Codex when an issue is labeled: ```yaml # .github/workflows/codex-auto-fix.yml name: Codex Auto Fix on: issues: types: [labeled] jobs: auto-fix: if: contains(github.event.label.name, 'codex-fix') runs-on: ubuntu-latest steps: - uses: openai/codex-action@v2 with: task: | Resolve Issue #${{ github.event.issue.number }}. Title: ${{ github.event.issue.title }} Body: ${{ github.event.issue.body }} create_pr: true pr_labels: "ai-generated,needs-review" env: OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }} GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} ``` With this workflow, any issue labeled `codex-fix` will have a PR automatically created by Codex. Your team focuses exclusively on review and approval.

Continuous improvement loop: ``` [Initial creation] ↓ [Run Codex tasks] ↓ [Discover unexpected behavior] ↓ [Add/fix instructions in AGENTS.md] ↓ [PR review with team] ↓ [Merge → retest] ↓ [Continuous improvement loop] ``` Think of AGENTS.md as a living document that grows with your project. Start minimal, and add instructions each time Codex makes an incorrect assumption. Over time, you will have a highly precise, project-aware agent.

Q1. How long should AGENTS.md be? A. Aim for 500–2,000 characters. Too long risks Codex overlooking key instructions. The guiding principle: only write what Codex would otherwise ask you every single time. Q2. Is AGENTS.md format the same as CLAUDE.md for Claude Code? A. The core structure is the same, but tool-specific command names and options differ. Extract shared content into a base file and maintain only tool-specific sections separately. Q3. Can I put MCP credentials in AGENTS.md? A. Absolutely not. Store API keys and secrets in environment variables (`~/.codex/env` or `.env`) and reference only the variable names in AGENTS.md. Q4. Does a subdirectory AGENTS.md completely override the root one? A. No — they are merged. Subdirectory instructions take priority over root instructions for conflicting rules, but non-conflicting instructions from both files remain active. Q5. How can I verify that AGENTS.md is working as intended? A. Run `codex explain --show-context` to inspect which configuration files Codex is loading and their full contents. This lets you confirm your instructions are being received correctly. Q6. Can Skills be published for others to use? A. Yes. Skills definition files (`.yaml`) can be published as npm packages. An open-source community of shareable Skills for common tasks is already growing rapidly.

Oflight provides end-to-end support for OpenAI Codex adoption, including AGENTS.md design, MCP integration, GitHub Actions setup, and team-wide rollout. Whether you are struggling to get Codex to follow your AGENTS.md, need help with MCP configuration, or want to scale Codex across your entire engineering team, we are here to help build the right AI-powered development environment for your organization. → Learn more about our AI Consulting Service