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.

10 min · Reviewed 2026

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

A one-line description of the repo and its main framework
How to install dependencies and what versions are pinned
How to run tests, lint, and typecheck
Code style rules that the linter does not enforce
Off-limits files or directories — generated code, vendor mirrors, encrypted secrets
How to run the dev server and where it listens
Known 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.

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

Open your main repo
Draft AGENTS.md in 30 minutes — first attempt only
Run a small Codex task and read the output
Note every place the agent guessed wrong — that is your AGENTS.md backlog

The big idea: the agent's quality is your repo's hygiene. Codex amplifies whatever onboarding clarity you already have.

End-of-lesson check

8 questions · take it digitally for instant feedback at tendril.neural-forge.io/learn/quiz/end-codex-repo-setup-creators

What is the main idea of "Setting Up Codex With Your Repo: AGENTS.md And Friends"?
1. Codex performs only as well as the project context you give it.
2. Use AI as the final authority for the whole decision
3. Avoid checking the answer once it sounds polished
4. Focus only on speed instead of judgment
Which concept is most central to "Setting Up Codex With Your Repo: AGENTS.md And Friends"?
1. setup script
2. AGENTS.md
3. project conventions
4. repo bootstrapping
Which use of AI fits this topic best?
1. Let the AI decide what matters without your review
2. Use the answer before checking whether it fits the situation
3. A one-line description of the repo and its main framework
4. Treat the AI output as automatically correct
What should a careful learner remember about "Keep it short"?
1. Use AI to draft or organize ideas about AGENTS.md, then verify before acting.
2. Skip the context so the tool can guess faster
3. Treat the output as private even after sharing it online
4. Use the answer without checking the source
You want to use AI after this lesson. What is the safest next step?
1. Act immediately because the AI answer is written clearly
2. Use AI for drafting and comparison, but verify before publishing or relying on it.
3. Hide uncertainty so the final answer looks cleaner
4. Use private or sensitive details before checking permission
How should AI output about AGENTS.md be treated?
1. As proof that no other source is needed
2. As a replacement for context, consent, or expert review
3. As a draft or helper output that still needs human judgment and verification
4. As something that becomes correct when it sounds confident
Name one way to verify an AI answer about AGENTS.md.
Which action would help you apply "Setting Up Codex With Your Repo: AGENTS.md And Friends" responsibly?
1. Use the tool to avoid thinking through the tradeoff
2. Keep going even if the output conflicts with a trusted source
3. Treat the AI output as automatically correct
4. How to install dependencies and what versions are pinned

← Back to interactive lesson

Tendril · Creators · Tools Literacy

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.

10 min · Reviewed 2026

The agent is a new hire

What AGENTS.md should contain

A one-line description of the repo and its main framework
How to install dependencies and what versions are pinned
How to run tests, lint, and typecheck
Code style rules that the linter does not enforce
Off-limits files or directories — generated code, vendor mirrors, encrypted secrets
How to run the dev server and where it listens
Known gotchas — sample data setup, env-var quirks, flaky tests

The setup script

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

Open your main repo
Draft AGENTS.md in 30 minutes — first attempt only
Run a small Codex task and read the output
Note every place the agent guessed wrong — that is your AGENTS.md backlog

The big idea: the agent's quality is your repo's hygiene. Codex amplifies whatever onboarding clarity you already have.

End-of-lesson check

8 questions · take it digitally for instant feedback at tendril.neural-forge.io/learn/quiz/end-codex-repo-setup-creators

What is the main idea of "Setting Up Codex With Your Repo: AGENTS.md And Friends"?
1. Codex performs only as well as the project context you give it.
2. Use AI as the final authority for the whole decision
3. Avoid checking the answer once it sounds polished
4. Focus only on speed instead of judgment
Which concept is most central to "Setting Up Codex With Your Repo: AGENTS.md And Friends"?
1. setup script
2. AGENTS.md
3. project conventions
4. repo bootstrapping
Which use of AI fits this topic best?
1. Let the AI decide what matters without your review
2. Use the answer before checking whether it fits the situation
3. A one-line description of the repo and its main framework
4. Treat the AI output as automatically correct
What should a careful learner remember about "Keep it short"?
1. Use AI to draft or organize ideas about AGENTS.md, then verify before acting.
2. Skip the context so the tool can guess faster
3. Treat the output as private even after sharing it online
4. Use the answer without checking the source
You want to use AI after this lesson. What is the safest next step?
1. Act immediately because the AI answer is written clearly
2. Use AI for drafting and comparison, but verify before publishing or relying on it.
3. Hide uncertainty so the final answer looks cleaner
4. Use private or sensitive details before checking permission
How should AI output about AGENTS.md be treated?
1. As proof that no other source is needed
2. As a replacement for context, consent, or expert review
3. As a draft or helper output that still needs human judgment and verification
4. As something that becomes correct when it sounds confident
Name one way to verify an AI answer about AGENTS.md.
Which action would help you apply "Setting Up Codex With Your Repo: AGENTS.md And Friends" responsibly?
1. Use the tool to avoid thinking through the tradeoff
2. Keep going even if the output conflicts with a trusted source
3. Treat the AI output as automatically correct
4. How to install dependencies and what versions are pinned

← Back to interactive lesson