Custom instructions with AGENTS.md | ChatGPT Learn
For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending
.md to the page URL.
ChatGPT
Start searching
API Dashboard
Try ChatGPT
Home
API
Overview
Get started with the OpenAI API
Models
Explore models and compare capabilities
Agents
Build persistent agents on hosted infrastructure
Tools
Connect models to tools and data
Audio & voice
Build speech and realtime voice experiences
Production
Deploy and scale your API integrations
API reference
Explore endpoints, parameters, and responses
ChatGPT
Sign in with ChatGPT
Apps powered by your user's ChatGPT plan
Plugins
Extend ChatGPT and Codex
Workspace Agents
Trigger published ChatGPT workspace agents
Commerce
Build commerce flows in ChatGPT
Ads
Publish and measure ads in ChatGPT
ChatGPT + Codex user docs
Guides and product docs for ChatGPT and Codex
Use cases
Example workflows and tasks teams can take on with ChatGPT or Codex
Docs
Use cases
Training
Resources
Resources
Showcase
Demo apps to get inspired
Blog
Learnings and experiences from developers
Cookbook
Notebook examples for building with OpenAI models
Learn
Docs, videos, and demo apps for building with OpenAI
Community
Programs, meetups, and support for builders
Overview      Features      Configuration      Developers      Security      Administration      Use Cases      Resources
Search the docs
Search docs
Suggested
responses createreasoning_effortrealtimeprompt caching
Primary navigation
API  ChatGPT  Docs  Use cases  Training  Resources  Resources
Search docs
Suggested
responses createreasoning_effortrealtimeprompt caching
Overview  Models  Agents  Tools  Audio & voice  Production  API reference
DocsOverview
Home
Get started
Quickstart
Using GPT-6
Key concepts
Core concepts
Responses API
Decisions API
Conversation state
Background mode
Streaming
WebSocket mode
Mid-turn steering
Multi-agent
Webhooks
File inputs
Compaction
Counting tokens
SDKs and CLI
OpenAI SDK
OpenAI CLI
Resources
Changelog
Deprecations
Supported countries
OpenAI Crawlers
Terms and policies
Legacy APIs
Agent Builder
Overview
Migration guide
Node reference
Safety in building agents
Evals
Getting started
Working with evals
Prompt optimizer
External models
Best practices
Graders
Fine-tuning
Optimization cycle
Supervised fine-tuning
Vision fine-tuning
Direct preference optimization
Reinforcement fine-tuning
RFT use cases
Best practices
Assistants API
Migration guide
Model catalog
Choose a model
Pricing
Model selection
Text and code
Text generation
Code generation
Structured output
Prompting
Overview
Prompt engineering
Citation formatting
Migration guide
Prompt generation
Frontend prompting
Reasoning
Reasoning models
Reasoning best practices
Images
Images and vision
Image input cost calculator
Image generation
Overview
Image prompting
Realtime and audio
Audio and speech
Getting started
Voice agents
Specialized models
Deep research
Embeddings
Moderation
Overview
Agents API
Overview
Quickstart
Architecture
Configuring Agents
Sessions
Run and continue sessions
Events and items
Manage sessions
Webhooks
Environments and sandboxes
OpenAI-hosted sandboxes
Self-hosted sandboxes
Sandbox lifecycle
Pre-warm sandboxes
Sandbox security
Files and artifacts
Tools and integrations
Web search
Computer use
Functions
MCP connections
Plugins
Vaults
Multi-agent
Observability and usage
Tracing
Errors and recovery
API reference
Bedrock Managed Agents
Agents SDK
Overview
Quickstart
Agent definitions
Models and providers
Running agents
Sandbox agents
Orchestration
Guardrails
Results and state
Integrations and observability
Evaluate agent workflows
ChatKit
Overview
Customize
Widgets
Actions
Advanced integrations
Overview
Function calling
Search and retrieval
Web search
File search
Retrieval
Connect tools and data
MCP servers
Secure MCP Tunnel
Build tool workflows
Skills
Tool search
Programmatic tool calling
Async tool calling
Computer and code
Shell
Computer use
Apply Patch
Local shell
Code interpreter
Media
Image generation
Overview
GPT-Live
Getting started
Prompting
Managing sessions
Delegation and tools
Migrate to GPT-Live
Partner integrations
Realtime API
Getting started
Prompting
Managing conversations
Voice activity detection
Tools and MCP
Build with voice
Voice agents
Connect voice to Decisions
Custom voices
Cost optimization
Connections
WebRTC
WebRTC with WARP
WebSockets
Telephony and SIP
Server-side controls
Audio processing
File transcription
Live transcription
Live translation
Text to speech
Audio in Chat Completions
Go live
Production best practices
Deployment checklist
Performance and quality
Fast mode
Ultrafast mode
Latency optimization
Predicted Outputs
Accuracy optimization
Cost and throughput
Cost optimization
Prompt caching
Prompt cache diagnostics
Batch
Flex processing
Safety and governance
Safety best practices
Red teaming
Daybreak
Safety checks
Safety classifiers
Cybersecurity checks
Misalignment monitoring
Enforcement notifications
Under-18 guidance
CSAM guidance
Content provenance
Your data
Private Safety Processing
Permissions
Infrastructure and access
Terraform provider
Overview
Projects and access
Service accounts
Rate limits and spend
Model, tool, and data controls
Import and reconciliation
Private Link
IP allowlist
Organization blocking
Mutual TLS
Workload identity federation
Federation rules
X.509 certificates
Kubernetes
AWS
Microsoft Azure
Google Cloud
Oracle Cloud Infrastructure
GitHub Actions
SPIFFE
IP egress ranges
Amazon Bedrock
Operations
Rate limits
Spend limits
Admin APIs
Error codes
Overview   Sign in with ChatGPT  Plugins  Workspace Agents  Commerce  Ads  ChatGPT + Codex user docs   Use cases
DocsOverview
Home
Quickstart
Request a client ID
Identity
On your website
In your ChatGPT plugin
ChatGPT plan usage
Overview
UI/UX guidelines
Registration and sign-in
Accounts and sessions
Models and inference
Codex app-server
Self-hosted VMs
Token reference
Errors and recovery
Preview limitations
Home
Quickstart
Core concepts
Plugin architecture
Skills
MCP server
Plan
Brainstorm use cases
Define tools
Build
Build an MCP server
Add UI to your MCP server (optional)
Add events to your MCP server (optional)
Extensions
Authenticate users
Build skills
Package your plugin
Examples
Test and publish
Connect and test your plugin
Submit and publish
Submission error reference
Conversion specs
Restaurant reservation spec
Get Quote spec
Product checkout spec
Guides
UI guidelines
Optimize Metadata
Submit a Claude Code plugin
Security & Privacy
Troubleshooting
Resources
Changelog
Plugin guidelines
MCP server review requirements
Plugin UI reference
Checkout API reference
Home
Get started
Trigger workspace agent runs
Authenticate with Workspace Agent access tokens
Home
Guides
Get started
Best practices
File Upload
Overview
Products
API
Overview
Feeds
Products
Promotions
Ads Overview
Measurement
Measurement Pixel
Multiple Pixels (Advanced)
Image Tag
Conversions API
Supported Events
Advertiser API
Overview
API Partner Setup
Campaign Management
Bidding & Budgets
Targeting
Product Feeds
Hotel Feeds (limited beta)
Conversion Tracking
Reporting
Troubleshooting
Account Management
API Reference
Authentication
Ad Account
Audit Logs
Campaigns
Ad Groups
Ads
Insights
Files
Conversion Setup
Overview  Features  Configuration  Developers  Security  Administration  Use Cases  Resources
DocsConfiguration
Home
Get started
Quickstart
Use ChatGPT
Get started with Work
Meet dots
Import from another agent
Foundations
Prompting
Model selection
Personalize ChatGPT
Skills & Plugins
Permissions
Explore
What's new
Models
Pricing
Glossary
Available on
ChatGPT desktop app
ChatGPT mobile app
ChatGPT on the web
Codex CLI
Codex IDE extension
Codex Cloud
Releases
Changelog
Feature Maturity
Open Source
Overview
Workflows
Projects and chats
Sites
Build plugins
Visualizations
Scheduled tasks
Long-running work
Notifications
Pets
Codex Micro
Capabilities
Browser
Computer use
Voice
Plugins
Sign in with ChatGPT
Web search
Image generation
Image inputs
Appshots
Browser extension
Work with files
dots
Meet dots
Getting started
Messaging
Tasks and memory
Computers and apps
Controls
ChatGPT Space
Overview
Getting started
Pages
Work with agents
Collaboration
Reference
Commands
Slash commands
Settings
Troubleshooting
Overview
Customization
Overview
Memories
Computer History
Config file
Config Basics
Advanced Config
Config Reference
Environment Variables
Sample Config
Agent configuration
AGENTS.md
Subagents
Speed
Rules
Extend ChatGPT and Codex
Record & Replay
MCP
Linux
Desktop app
Windows
Desktop app
Windows sandbox
WSL
Overview
Development workflows
Code review
Integrated terminal
Extend and automate
Build skills
Site tools (WebMCP)
Annotations Extensibility
Hooks
Environments
Modes
Local environments
Git worktrees
Codex Cloud
Cloud environments
Build with Codex
Codex SDK
App Server
GitHub Action
Non-interactive mode
Third-party integrations
GitHub
GitLab (Beta)
Slack
Linear
Reference
CLI customization
Developer commands
Developer settings
Overview
Permissions
Profiles
Sandboxing
Auto-review
Agent approvals & security
Codex Security
Overview
Codex Security plugin
Quickstart
Run a security scan
Run a deep scan
Review code changes
Use the Security workbench
Triage a backlog
Fix findings
Propose security hardening
Write vulnerability reports
Export and track findings
Changelog
Codex Security CLI
Quickstart
Run bulk scans
Run scans in CI
GitLab CI/CD
Reference
FAQ
TypeScript SDK
Codex Security Cloud
Setup
Security Review
Improving the threat model
FAQ
Cyber safety
Models & Trusted Access
Recommended configuration
Overview
Getting started
Admin rollout guide
Admin plugin
Feature setup
Dots
Space
Teams and Team Tasks
ChatGPT in Slack and Teams
Workspace connections
Local computer access for Work Cloud and dots
Sites
Identity and access
Authentication overview
Groups and provisioning
Dynamic groups
User lifecycle management
Roles and workspace permissions
Personal access tokens
Service accounts
Deployment and configuration
Windows app deployment
Manage app updates
Managed configuration
Remote connections
Workspace model availability
Amazon Bedrock
Bedrock GovCloud configuration
Connect to a gateway
Sign in with ChatGPT
Use API/provider credentials
Roll out a gateway
Gateway compatibility
Bedrock through LiteLLM
ChatGPT Work
Overview
Cloud security
Local security
Usage and cost
Admin FAQ
Collaboration and sharing
GPTs and sharing
Plugins and connections
Plugin controls
Plugin management
Skill controls
Migrate custom GPTs to plugins
Usage and analytics
Workspace analytics
Usage Insights
Analytics API
Security and compliance
Governance
Agent security
Prisma AIRS
HIPAA configuration
Compliance API and audit events
Explore use cases
Collections
Home
Videos
Showcase
OpenAI Academy
Online trainings
Community
Codex Ambassadors
Codex for Students
Codex for Open Source
Events
Blog
Company blog
Developer blog
Explore use cases
Collections
Home
Videos
Showcase
OpenAI Academy
Online trainings
Community
Codex Ambassadors
Codex for Students
Codex for Open Source
Events
Blog
Company blog
Developer blog
Showcase   Blog  Cookbook  Learn  Community
DocsSelect...
All posts
Recent
Bringing my LED display to life with GPT-Live-1 and Codex
Rethinking skills and prompts for GPT-6 Astra
Architectural visualization with Astra
Building games with Astra
Meet Rosalind Workbench: Empowering every scientist to be their own research team
Topics
General
API
Apps SDK
Audio
Codex
Life sciences
Home
Topics
Sign-in with ChatGPT
Agents
Evals
Multimodal
Text
Guardrails
Optimization
ChatGPT
Codex
gpt-oss
Contribute
Cookbook on GitHub
Home
OpenAI Developers plugin
Docs MCP
Categories
Demo apps
Videos
Topics
Agents
Audio & Voice
Computer Use
Codex
Evals
gpt-oss
Fine-tuning
Image generation
Scaling
Tools
Video generation
Community
Programs
Codex Ambassadors
Meet the ambassadors
Codex for Students
Codex for Open Source
OpenAI for Startups
Spaces
Events
Developer Forum
Discord
Reddit
X
API Dashboard
Try ChatGPT
Overview
Customization
Overview
Memories
Computer History
Config file
Config Basics
Advanced Config
Config Reference
Environment Variables
Sample Config
Agent configuration
AGENTS.md
Subagents
Speed
Rules
Extend ChatGPT and Codex
Record & Replay
MCP
Linux
Desktop app
Windows
Desktop app
Windows sandbox
WSL
Copy Page
Custom instructions with AGENTS.md
Give Codex extra instructions and context for your project
Copy Page
Codex reads AGENTS.md files before doing any work. By layering global guidance with project-specific overrides, you can start each task with consistent expectations, no matter which repository you open.
How Codex discovers guidance
Codex builds an instruction chain when it starts (once per run; in the TUI this usually means once per launched session). Discovery follows this precedence order:
Global scope: In your Codex home directory (defaults to ~/.codex, unless you set CODEX_HOME), Codex reads AGENTS.override.md if it exists. Otherwise, Codex reads AGENTS.md. Codex uses only the first non-empty file at this level.
Project scope: Starting at the project root (typically the Git root), Codex walks down to your current working directory. If Codex cannot find a project root, it only checks the current directory. In each directory along the path, it checks for AGENTS.override.md, then AGENTS.md, then any fallback names in project_doc_fallback_filenames. Codex includes at most one file per directory.
Merge order: Codex concatenates files from the root down, joining them with blank lines. Files closer to your current directory override earlier guidance because they appear later in the combined prompt.
Codex skips empty files and stops adding files once the combined size reaches the limit defined by project_doc_max_bytes (32 KiB by default). For details on these knobs, see Project instructions discovery. Raise the limit or split instructions across nested directories when you hit the cap.
Create global guidance
Create persistent defaults in your Codex home directory so every repository inherits your working agreements.
Ensure the directory exists:
mkdir -p ~/.codex
Create ~/.codex/AGENTS.md with reusable preferences:
# ~/.codex/AGENTS.md
## Working agreements
- Always run `npm test` after modifying JavaScript files.
- Prefer `pnpm` when installing dependencies.
- Ask for confirmation before adding new production dependencies.
Run Codex anywhere to confirm it loads the file:
codex --ask-for-approval never "Summarize the current instructions."
Expected: Codex quotes the items from ~/.codex/AGENTS.md before proposing work.
Use ~/.codex/AGENTS.override.md when you need a temporary global override without deleting the base file. Remove the override to restore the shared guidance.
Layer project instructions
Repository-level files keep Codex aware of project norms while still inheriting your global defaults.
In your repository root, add an AGENTS.md that covers basic setup:
# AGENTS.md
## Repository expectations
- Run `npm run lint` before opening a pull request.
- Document public utilities in `docs/` when you change behavior.
Add overrides in nested directories when specific teams need different rules. For example, inside services/payments/ create AGENTS.override.md:
# services/payments/AGENTS.override.md
## Payments service rules
- Use `make test-payments` instead of `npm test`.
- Never rotate API keys without notifying the security channel.
Start Codex from the payments directory:
codex --cd services/payments --ask-for-approval never "List the instruction sources you loaded."
Expected: Codex reports the global file first, the repository root AGENTS.md second, and the payments override last.
Codex stops searching once it reaches your current directory, so place overrides as close to specialized work as possible.
Here is a sample repository after you add a global file and a payments-specific override:
AGENTS.md    Repository expectations
services/
payments/
AGENTS.md    Ignored because an override exists
AGENTS.override.md    Payments service rules
README.md
search/
AGENTS.md
…
Add code review rules
For Codex code review in GitHub,
add a ## Code Review Rules section to the AGENTS.md closest to the code the
rules govern. Put repository-wide checks at the root and service-specific
checks in a nested file.
## Code Review Rules
### Experiment cohorts
- Do not filter treatment comparisons on post-exposure behavior, including conversion or retention.
Safe path: build cohorts from assignment or exposure; report conversion as an outcome.
Keep rules concise, explain the behavior to flag and any safe path or
exception, and reserve formatting and lint checks for CI. See Customize what
Codex reviews for
setup and rule-writing guidance.
Customize fallback filenames
If your repository already uses a different filename (for example TEAM_GUIDE.md), add it to the fallback list so Codex treats it like an instructions file.
Edit your Codex configuration:
# ~/.codex/config.toml
project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]
project_doc_max_bytes = 65536
Restart Codex or run a new command so the updated configuration loads.
Now Codex checks each directory in this order: AGENTS.override.md, AGENTS.md, TEAM_GUIDE.md, .agents.md. Filenames not on this list are ignored for instruction discovery. The larger byte limit allows more combined guidance before truncation.
With the fallback list in place, Codex treats the alternate files as instructions:
TEAM_GUIDE.md    Detected via fallback list
.agents.md    Fallback file in root
support/
AGENTS.override.md    Overrides fallback guidance
playbooks/
…
Set the CODEX_HOME environment variable when you want a different profile, such as a project-specific automation user:
CODEX_HOME=$(pwd)/.codex codex exec "List active instruction sources"
Expected: The output lists files relative to the custom .codex directory.
Verify your setup
Run codex --ask-for-approval never "Summarize the current instructions." from a repository root. Codex should echo guidance from global and project files in precedence order.
Use codex --cd subdir --ask-for-approval never "Show which instruction files are active." to confirm nested overrides replace broader rules.
To audit which instruction files Codex loaded, opt into a plaintext TUI log with codex -c log_dir=./.codex-log and check ./.codex-log/codex-tui.log, or inspect the most recent session-*.jsonl file if you enabled session logging.
If instructions look stale, restart Codex in the target directory. Codex rebuilds the instruction chain on every run (and at the start of each TUI session), so there is no cache to clear manually.
Troubleshoot discovery issues
Nothing loads: Verify you are in the intended repository and that codex status reports the workspace root you expect. Ensure instruction files contain content; Codex ignores empty files.
Wrong guidance appears: Look for an AGENTS.override.md higher in the directory tree or under your Codex home. Rename or remove the override to fall back to the regular file.
Codex ignores fallback names: Confirm you listed the names in project_doc_fallback_filenames without typos, then restart Codex so the updated configuration takes effect.
Instructions truncated: Raise project_doc_max_bytes or split large files across nested directories to keep critical guidance intact.
Profile confusion: Run echo $CODEX_HOME before launching Codex. A non-default value points Codex at a different home directory than the one you edited.
Next steps
Visit the official AGENTS.md website for more information.
Review Prompting Codex for conversational patterns that pair well with persistent guidance.
Next
Subagents
Ask AI
Docs agent
Loading docs agent...