Project Files

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

What Are the .claude, .codex, and .agents Folders?

The .claude, .codex, and .agents folders hold settings and skills for Claude and Codex. Learn what goes in each, where they are on a Mac, and how to use them.

These hidden folders hold the settings, skills, and memory that AI coding tools use. The .claude folder belongs to Anthropic Claude. The .codex folder belongs to ChatGPT Codex. The .agents folder holds skills that Codex and several other AI coding tools read. You'll find a copy of each in your home directory, and often another inside a project.

Many people see these folders as clutter that they never open. Experienced users treat a project's copies as an essential part of the project, to be kept in Git with the code. They hold shared rules about what an AI agent may do without asking, skills that everyone on the project can use, and a file for your own agent rules. With them, a project works the same way in every session and for every person who opens it, and sets the rules for what an AI agent may do. Often an AGENTS.md instructions file is the only needed file, though, so add to these folders only when there is a need.

Here's something about these folders that isn't obvious. It's no big secret but it will give you insight into how an AI agent works. These folders in your home directory hold an AI agent's record of your past work. Claude saves a transcript of every session in ~/.claude/projects. Codex saves its own in ~/.codex/sessions. With the saved transcript, you can resume an old conversation where you left off. Claude also keeps notes it writes for itself about each project in ~/.claude/projects, and reads them at the start of every new session. Delete the home directory ~/.claude or ~/.codex folders and that history disappears, along with your settings. Deleting a project's .claude or .codex folder destroys only a project's settings.

The What's in a Project Folder? article explains the other files you'll find beside these folders in a project. These folders are one part of how you set up a Mac for development.

Two copies: your home directory and the project

Each AI agent reads its folders from two places:

  • Your home directory - ~/.claude and ~/.codex hold your own settings, which apply in every project on your Mac. The ~ stands for your home directory, such as /Users/yourname. Skills in ~/.agents/skills also work in every project.
  • A project folder - a .claude, .codex or .agents folder inside a project holds settings for that project only. When you commit it to Git, everyone who works on the project gets the same settings.

Where the two disagree, the project's setting usually wins over your own. For rules that apply to every project, set up the ~/.claude and ~/.codex files in your home directory and avoid making duplicate rules in every project, to avoid maintenance overhead. Use project-level .claude, .codex or .agents folders only for rules that are specific to one project.

Anthropic says most people who use Claude only ever edit CLAUDE.md and settings.json, so don't expect to use everything listed below.

What's in the .claude folder

Here's what a project's .claude folder can hold. Claude creates some of these files as you work. You add the rest yourself, or ask an AI agent to add them:

.claude/
├── settings.json        shared settings, such as permissions and hooks
├── settings.local.json  your own settings for this project
├── skills/              the project's skills, one folder each
├── commands/            older single-file commands
├── agents/              subagents, helpers for separate tasks
└── rules/               instruction files for parts of the project

The skills folder holds agent skills, each in its own folder with a SKILL.md file. A file in commands works the same way as a skill, and older projects still use them. Hooks, commands that Claude runs automatically at certain moments, are set in settings.json or settings.local.json. Their scripts often go in a .claude/hooks folder. A project's CLAUDE.md instruction file can sit in .claude too, though it is usually in the project's top folder.

In your home directory, ~/.claude holds your personal CLAUDE.md, settings.json, and skills, which apply everywhere. It also holds ~/.claude/projects, where Claude keeps transcripts of your sessions and its own notes about each project (its auto memory). The transcripts are plain text. If a tool mistakenly read a .env file during a session, you would search for it in there. Claude deletes old transcripts after 30 days unless you change that setting. Beside the folder, a file named ~/.claude.json holds your account details and the MCP servers you added for yourself (Add MCP Servers to Claude explains more, as well as the project's shared .mcp.json file, which sits in the project's top folder rather than in .claude).

What's in the .codex folder

A project's .codex folder holds Codex's settings for that project, in a file named config.toml, and can also hold hooks (hooks.json) and rules. Codex reads a project's .codex folder only after you tell it you trust the project.

In your home directory, ~/.codex/config.toml holds your own Codex settings, including the MCP servers you've added (Developer Setup for MCP Servers shows how). Your personal instruction file for Codex, ~/.codex/AGENTS.md, is there too. Codex also keeps its history, logs, and caches in ~/.codex.

What's in the .agents folder

Codex doesn't keep skills in .codex. It reads them from .agents/skills in a project, and from ~/.agents/skills in your home directory. Cursor, GitHub Copilot, Gemini CLI, Zed, and Warp also read ~/.agents/skills, so a skill you put there works in several AI coding tools.

Claude reads skills only from its own folders. To use one skill in both Claude and Codex, keep it in .agents/skills and add a link to it in .claude/skills, as Developer Setup for Agent Skills shows. The "Set Up Your Mac" starter projects take the simpler route and include a copy of each skill in both .claude and .agents.

There are proposals to use .agents for every kind of setting for AI agents, not only skills, so that all AI agents share one folder. None of them is a settled standard (so far, in November 2026), so treat .agents as a folder for skills.

What to commit to Git

Commit the parts of these folders that everyone on the project should share. Keep your personal files out of Git:

  • Commit - .claude/settings.json, and the skills, commands, agents, and rules folders inside .claude, plus the project's .codex and .agents folders.
  • Keep out of Git - .claude/settings.local.json, which holds your own permissions for the project. Claude first writes it when you answer "Yes, and don't ask again" to a permission question, and then adds it to your personal Git ignore list (~/.config/git/ignore), so Git leaves it out of every project. If you create the file yourself, add it to the project's .gitignore file. Do the same for a CLAUDE.local.md in the project's top folder, which Claude doesn't ignore for you.
  • Never copy into a project - anything from ~/.claude, ~/.claude.json or ~/.codex. Those hold API keys, your account details, and transcripts of your sessions.

See the folders on a Mac

Names that start with a dot are hidden in the Finder. Open the project folder in a Finder window and press Command + Shift + . (period) to show hidden items. Press it again to hide them. Show Hidden Files on Mac explains more.

To open the copy in your home directory, press Command + Shift + G in the Finder, type ~/.claude or ~/.codex, and press Return.

In a terminal application, the -a option of ls lists hidden names. Open a terminal application, move into your project folder with cd, and list everything in it:

$ ls -a

To list what is in your home directory's copy, give ls the folder's path:

$ ls -a ~/.claude

Read them before you trust a project

A project's .claude/settings.json or .codex folder can contain hooks. Anyone who can change the project can add one that runs commands on your Mac. Claude holds back a project's hooks until you trust the folder. Codex ignores a project's .codex folder until you trust the project. So before you trust a project you downloaded, open these folders and read what they hold, especially any hooks and scripts. Hooks for Claude Code and Codex explains what to check.

Now you can open any project, show its hidden folders, and tell which settings belong to the project and which belong to you. Start with an instruction file. Add a setting, a skill, or a hook to these folders when you want an AI agent to work differently in this project.

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.