Lesson 475 of 2116
Setting Up Codex With Your Repo: AGENTS.md And Friends
Codex performs only as well as the project context you give it. A short AGENTS.md, clean setup script, and explicit conventions cut hallucinations dramatically.
Lesson map
What this lesson covers
Learning path
The main moves in order
- 1The agent is a new hire
- 2AGENTS.md
- 3setup script
- 4project conventions
Concept cluster
Terms to connect while reading
Section 1
The agent is a new hire
Imagine onboarding a sharp new engineer who has never seen your repo. What would you put in their first-day doc? Codex needs the same: where the entry points are, how to run tests, what the deploy story is, what the conventions are, and what the gotchas are. That doc is AGENTS.md.
What AGENTS.md should contain
- 1A one-line description of the repo and its main framework
- 2How to install dependencies and what versions are pinned
- 3How to run tests, lint, and typecheck
- 4Code style rules that the linter does not enforce
- 5Off-limits files or directories — generated code, vendor mirrors, encrypted secrets
- 6How to run the dev server and where it listens
- 7Known gotchas — sample data setup, env-var quirks, flaky tests
The setup script
For the cloud, you need a setup script that takes a clean container to ready-to-code in under a few minutes. Think 'install Node, install pnpm, install deps, generate Prisma client, copy a sample env file'. If your setup is twenty steps, your repo is not Codex-ready — and probably not new-hire-ready either.
Compare the options
| Symptom | Likely cause | Fix |
|---|---|---|
| Agent edits the wrong files | Convention not stated | Add 'edit X for Y' guidance to AGENTS.md |
| Agent runs the wrong test command | Multiple test runners present | State the canonical command in AGENTS.md |
| Agent can't reach the database | Missing env in setup | Add the env init to the cloud setup script |
| Agent generates code in a deprecated style | Old code lying around | Mark deprecated dirs as off-limits |
Applied exercise
- 1Open your main repo
- 2Draft AGENTS.md in 30 minutes — first attempt only
- 3Run a small Codex task and read the output
- 4Note every place the agent guessed wrong — that is your AGENTS.md backlog
Key terms in this lesson
The big idea: the agent's quality is your repo's hygiene. Codex amplifies whatever onboarding clarity you already have.
End-of-lesson quiz
Check what stuck
15 questions · Score saves to your progress.
Tutor
Curious about “Setting Up Codex With Your Repo: AGENTS.md And Friends”?
Ask anything about this lesson. I’ll answer using just what you’re reading — short, friendly, grounded.
Progress saved locally in this browser. Sign in to sync across devices.
Related lessons
Keep going
Creators · 9 min
What Perplexity Is: Search-Augmented LLM, Not A Chatbot
Perplexity is built around the idea that every answer should cite its sources. Treating it like ChatGPT misses the point — and the reliability gap that comes with it.
Creators · 10 min
Spaces: Building Team Knowledge Bases In Perplexity
Spaces are Perplexity's project containers — system prompts, files, and shared chat history. They turn the search engine into a research workspace.
Creators · 10 min
Comet Browser: What It Does That Atlas And Operator Don't
Comet is Perplexity's full browser with a research-native sidebar and an action-capable agent. It plays differently than ChatGPT Atlas or Operator — and the differences matter.