Developer Setup

Written & tested for accuracy by a developer (not AI) · Updated October 2026

Developer Setup for Agent Instructions

How to use the files CLAUDE.md and AGENTS.md on a Mac. Recommended agent instructions, where the files go, and how to share one file with both Claude Code and Codex.

Agent instructions are notes that an AI coding agent reads at the start of every session, before your first message. They tell the agent what it can't learn elsewhere: the commands that build and test your project, the conventions you follow, the things it should never do, and how your Mac is set up. Use agent instructions so you don't have to repeat yourself in every conversation.

Claude Code reads a file named CLAUDE.md. Codex and most other AI coding tools read a file named AGENTS.md, an open format that its makers call "a README for agents". Both are plain Markdown text files. Claude Code can now read AGENTS.md too, so one file can serve both agents.

For advice on what to write in these files, with examples, see CLAUDE.md and AGENTS.md Best Practices.

How it works

An agent loads every instruction file that applies into its context (its working memory) when a session starts. Agent instructions can be loaded from a personal file, which applies to every project, then the project's files, from the project's top folder down to the folder you're working in. All of them apply together. Where two disagree, the file proximate to your work usually wins. What you type in a prompt takes precedence over any files of agent instructions.

The files are guidance, not rules the agent can't break. Anthropic's documentation says Claude treats them "as context, not enforced configuration". The agent reads every line in every session, so a long file costs context and makes each rule easier to miss. That's why you should keep agent instructions short and focused.

The "Set Up Your Mac" apps add a note to your agent instructions, in addition to installing Claude Code and Codex. This page explains what the app adds, then where the files go, how to create them, how to use one file for both agents, and how to check what your agent loaded. It is one topic in "Set Up Your Mac", my guide to setting up a Mac for software development.

Agent instructions in the "Set Up Your Mac" apps

Near the end of the setup process, the "Set Up Your Mac" app offers to tell your AI agent how your Mac is set up. An agent that doesn't know your configuration may make incorrect assumptions, for example by installing a second copy of Python or by changing your PATH. The app adds a short note to your personal instruction files, ~/.claude/CLAUDE.md for Claude Code and ~/.codex/AGENTS.md for Codex. The note says which tool manages each language, such as uv for Python, and where your shell settings and API keys live.

The note is clearly marked, and the app adds it at the end of any instructions you already have, after saving a backup copy of the file (CLAUDE.md.bak or AGENTS.md.bak). If your ~/.claude/CLAUDE.md already imports ~/.codex/AGENTS.md (see "Add personal instructions for all your projects" below), the app writes the note only once, in the Codex file. The app can't update the note later, so edit it yourself if your setup changes.

The files ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md are there so you don't have to create them later.

If you choose to install an example project in the app, it comes with a CLAUDE.md and an AGENTS.md, arranged as described in "Use one AGENTS.md for Claude Code and Codex" below. Looking at the example project files will help you learn how to set up a project with agent instructions.

Where CLAUDE.md and AGENTS.md go on a Mac

Each agent reads a personal file in your home folder, which applies to every project, and project files inside a project's folder, which apply only to that project. Commit the project files to Git, and everyone who works on the project gets them too.

  • Claude Code - your personal file is ~/.claude/CLAUDE.md. In a project, put CLAUDE.md in the project's top folder (or in .claude/CLAUDE.md). A CLAUDE.md in a subfolder loads when Claude works on a file in that folder.
  • Codex - your personal file is ~/.codex/AGENTS.md. In a project, put AGENTS.md in the project's top folder, and add more in subfolders if parts of the project need their own instructions. Codex reads them from the project's top folder down to the folder you're working in.
  • Other AI coding tools - most read AGENTS.md in a project. See "Set up instruction files in other AI coding tools" below.

Don't put a CLAUDE.md or AGENTS.md directly in your home folder (~/CLAUDE.md or ~/AGENTS.md). Codex reads only ~/.codex/AGENTS.md and the project's own folders, so it skips ~/AGENTS.md. A ~/CLAUDE.md is worse: it stops Claude Code from reading the AGENTS.md in every project inside your home folder.

To see your personal files, open a terminal application and run:

$ cat ~/.claude/CLAUDE.md ~/.codex/AGENTS.md

You'll see the text of each file. If one doesn't exist yet, you'll see "No such file or directory" for it.

Folders whose names start with a dot, such as .claude, are hidden in the Finder. Press Command + Shift + . (period) in a Finder window to show them. See Show Hidden Files on Mac.

Create a CLAUDE.md or AGENTS.md file

If you're not using the "Set Up Your Mac" apps to set up your agent instructions, you can create them yourself. Or you may want to create customized agent instructions for your projects.

You can ask an agent to write a first draft with a shortcut command. Open a project and type /init:

  • Claude Code - /init reads your project and writes a starter CLAUDE.md. If the project already has an AGENTS.md, the new CLAUDE.md imports it (see the next section), and AGENTS.md stays as it is. If the project already has a CLAUDE.md, /init suggests improvements rather than replacing it.
  • Codex - /init writes a starter AGENTS.md in the current folder.

Review the draft and cut what you don't need. See CLAUDE.md and AGENTS.md Best Practices for what to keep.

You can also write the file yourself in a code editor or a Markdown editor. It needs no special format. A short list works well. Here's an example:

# Project notes

- Run the tests with `npm test` before you finish a task.
- Write new code in TypeScript, not JavaScript.
- Never edit the generated files in `dist/`.

To add a rule later, edit the file, or ask your agent to do it. For example: "Add to AGENTS.md: run the tests before you finish a task." In Claude Code, type /memory to open your instruction files for editing.

Use one AGENTS.md for Claude Code and Codex

Claude Code and Codex look for different files, so a project that uses both agents needs both to see the same instructions.

Here's a trick to share one file for both agents. This is especially useful for developers who use both Claude Code and Codex on the same project. Put the instructions in AGENTS.md, and make CLAUDE.md a single line:

@AGENTS.md

In Claude Code, a line that starts with @ and a file's path imports that file, so Claude reads AGENTS.md through CLAUDE.md. Codex reads AGENTS.md directly and ignores CLAUDE.md. If you have notes that only Claude Code should see, add them below the @AGENTS.md line.

Homebrew's own project uses exactly this arrangement. If you have Homebrew, you can see it on your Mac:

$ cat "$(brew --repository)/CLAUDE.md"

You'll see the single line @AGENTS.md.

Since version 2.1.277 (September 2026), Claude Code reads AGENTS.md on its own when a project has no CLAUDE.md, so a project with only AGENTS.md works too. The one-line CLAUDE.md still helps, because some sessions read only CLAUDE.md. Older versions of Claude Code don't read AGENTS.md on their own, and sometimes the first session after you update from one of them doesn't either. Two things also stop Claude Code from reading AGENTS.md on its own: a CLAUDE.local.md in the project, and a CLAUDE.md in any folder above it. With the one-line CLAUDE.md, neither matters. If you rely on AGENTS.md alone, type /config in Claude Code and set Project instructions to claude-md-and-agents-md, which reads both files.

There are two other ways to share one file:

  • A symbolic link (a pointer to another file): ln -s AGENTS.md CLAUDE.md in the project's top folder. Claude Code reads the link, but its editing tools won't write through one, so ask it to edit AGENTS.md instead.
  • Codex reads CLAUDE.md: add project_doc_fallback_filenames = ["CLAUDE.md"] to ~/.codex/config.toml. Codex then reads CLAUDE.md in any folder that has no AGENTS.md.

Add personal instructions for all your projects

Your personal file applies in every project, so it is the place to say how your Mac is set up. Use it for agent habits you want used everywhere. Here is a short example:

# My Mac

- Homebrew installs command-line tools (`brew install <name>`).
- Python: use uv. Run scripts with `uv run` and add packages with `uv add`.
- Node: use mise. Run `mise use node@<version>` in a project.
- Ask before you change my shell files, `~/.zprofile` and `~/.zshrc`.

If you use both Claude Code and Codex, you have two ways to give them the same personal instructions:

  • Two files - keep ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md separately, as the "Set Up Your Mac" app does. Each agent always reads its own file. When you change one, change the other to match.
  • One file - keep your instructions in ~/.codex/AGENTS.md, and make ~/.claude/CLAUDE.md the single line @~/.codex/AGENTS.md. Both agents then read the same text. One limit: Claude Desktop conversations that work in a folder on your Mac, outside the Code tab, skip an import like this one. Those conversations take their own account-wide instructions from Settings > General > Instructions for Claude.

Codex reads at most 32 KiB of instructions (about 32,000 characters), counting your personal file and the project's files together, and stops adding files at that limit. That's one more reason to keep your personal file short.

Check which instructions your agent loaded

  • Claude Code - type /memory to see the instruction files loaded in this session, and open one to edit it. Type /context to see how much of the agent's context they take up. When Claude Code reads an AGENTS.md on its own, it shows a line such as "no CLAUDE.md found; AGENTS.md loaded".
  • Codex - ask "Summarize the current instructions." Codex summarizes what it was given, from your personal file and the project's files, though it may not say which file each part came from.

Keep personal notes out of a shared project

A project's CLAUDE.md or AGENTS.md is usually committed to Git, so everyone on the project shares it. For notes only you need, such as the address of your own test server, Claude Code reads a CLAUDE.local.md in the project. Add CLAUDE.local.md to the project's .gitignore file, so Git leaves it out.

A CLAUDE.local.md also stops Claude Code from reading the project's AGENTS.md on its own, unless the project's CLAUDE.md imports it or you set Project instructions to read both files (see above).

Codex has no file for personal notes in a project. If a folder holds an AGENTS.override.md, Codex reads it in place of that folder's AGENTS.md, which is useful for a temporary change. Keep it out of Git too.

Set up instruction files in other AI coding tools

Most AI coding tools read AGENTS.md, and a few read CLAUDE.md as well:

  • Gemini CLI - reads GEMINI.md, with a personal file at ~/.gemini/GEMINI.md. Add AGENTS.md to its context.fileName setting to make it read AGENTS.md.
  • GitHub Copilot - on GitHub, reads .github/copilot-instructions.md and AGENTS.md. Its command-line tool also reads CLAUDE.md, and VS Code can read both AGENTS.md and CLAUDE.md.
  • Cursor - reads AGENTS.md, and its own rules in the .cursor/rules folder.
  • Zed - reads the first instruction file it finds from a list of names, with AGENTS.md ahead of CLAUDE.md. Personal instructions go in ~/.config/zed/AGENTS.md.
  • Warp - reads AGENTS.md (or its older WARP.md), with global rules in Warp's settings.
  • Devin Desktop (formerly Windsurf) - reads AGENTS.md, and its own rules in the .devin/rules/ folder.

Claude's chat, on claude.ai and in Claude Desktop outside the Code tab, uses no instruction files. Set its account-wide instructions in Settings > General > Instructions for Claude.

Know what agent instructions can't do

Instructions are guidance, so an agent can still miss one, especially in a long file or a long session. For an action that must happen every time, such as formatting each file after an edit, Claude Code and Codex use hooks: commands that run automatically at set moments. To stop an agent from doing something at all, use its permission settings.

Claude Code also keeps notes for itself, called auto memory, in ~/.claude/projects/. Those are Claude's own notes about your projects, not your instructions. Type /memory to read them, edit them, or turn auto memory off.

A skill is another kind of instructions: one the agent loads only when a task calls for it, rather than in every session. Put a long procedure you use now and then in a skill, not in your instruction file. See Developer Setup for Agent Skills, and MCP or Skills or CLI? for how skills compare with MCP servers and command-line tools.

Learn more about agent instructions

Continue setting up your Mac

Don't miss the full visual roadmap and checklist that shows how to set up a Mac for software development, with all the essential tools and settings you might not yet know about.