When you use Codex every day, you eventually repeat the same setup over and over: answer in a specific language, use a specific output format, keep explanations short, or avoid certain coding styles.
That repetition is exactly what .codex/AGENTS.md is for.
This file lets you define persistent instructions that Codex can read automatically, so you do not have to restate your preferences every time you start a new session.
What .codex/AGENTS.md does
Think of it as a standing instruction file for your local Codex environment. Instead of rewriting your working preferences in every prompt, you put them in one Markdown file.
From there, Codex can keep your responses and editing behavior more consistent.
This is useful when you want things like:
- one preferred language for replies
- stable formatting rules
- specific coding conventions
- a fixed response structure
Where the file lives
Create a hidden .codex directory in your home folder, then place AGENTS.md inside it.
mkdir -p ~/.codex touch ~/.codex/AGENTS.md
On macOS or Linux, ~ means your home directory.
Examples:
- macOS:
/Users/your-name/.codex/AGENTS.md - Linux:
/home/your-name/.codex/AGENTS.md - Windows equivalent environments may map this differently, but the idea is the same
Why this path can feel confusing
People often get stuck on three small details:
~is shorthand for your home directory.codexstarts with a dot, so it is a hidden folderAGENTS.mdis just a Markdown file, not a special binary format
Once you understand that, the setup is simple: create a folder, create a file, write your instructions.
A practical starter example
# AGENTS.md ## Default rules - Reply in English. - Keep answers concise and structured. - Explain code changes before listing follow-up steps. ## Writing style - Avoid unnecessary filler. - Prefer direct technical explanations. - Use bullet lists only when they help readability. ## Code preferences - Keep edits minimal. - Preserve existing project conventions. - Add comments only where they clarify non-obvious logic.
This is enough to make Codex feel noticeably more consistent.
What makes a good instruction file
The best AGENTS.md files are specific without becoming bloated.
Good instructions usually define:
- the language you want
- how verbose answers should be
- how code should be edited
- any formatting rules you care about
- any hard constraints you want respected
Bad instruction files tend to be vague, contradictory, or overloaded with too many micro-rules.
How to use it in real work
- Start Codex normally.
- Let it load your standing instructions.
- Add only the task-specific context in the prompt.
That means your prompts can focus on the work itself instead of repeating your personal defaults.
Optional: separate behavior by use case
## Development - Focus on minimal diffs. - Explain risks first. ## Writing - Prefer natural prose over lists. - Keep titles short and clear. ## Marketing - Optimize for clarity and SEO intent.
You are not building a legal document. You are building a stable operating profile.
How to verify it is working
A simple test is to start a fresh session and ask Codex to do something that should reflect your defaults.
If your file says "reply in English" and "keep responses concise," a new session should already lean that way without being reminded.
Operating tips
- review the file once a month
- remove rules you no longer care about
- keep instructions short enough to remain coherent
- prefer a few strong defaults over many weak ones
If a rule matters every session, it belongs here. If it matters only once, keep it in the prompt.
Summary
.codex/AGENTS.md is one of the simplest ways to make Codex feel like your own working environment instead of a generic assistant.
It is a small file, but it has a large effect on consistency, speed, and the amount of repeated prompting you need to do.
