We use cookies to understand how you use our site and improve your experience. Cookie policy
Last updated:
CLAUDE.md and AGENTS.md are the files your agent reads first to learn about your workspace. CLAUDE.md is for Claude Code. AGENTS.md is for Codex. Both serve the same purpose: tell the agent who you are, what this workspace is for, and how you work.
A good one of these files is the difference between an agent that needs you to repeat yourself every chat and one that picks up where you left off.
In the root of your workspace folder, alongside your top-level folders.
your-workspace/
├── CLAUDE.md
├── AGENTS.md
├── accounts/
├── playbooks/
└── ...
If you only use Claude Code, you only need CLAUDE.md. If you only use Codex, only AGENTS.md. If you use both, keep them in sync (the easiest way is to have one be a copy of the other, and update them together).
The agent reads this file at the start of every session. Keep it scannable, not exhaustive.
A good CLAUDE.md or AGENTS.md covers:
What to leave out:
When you turn on the starting guide for a new folder, Palette writes your first CLAUDE.md or AGENTS.md based on:
It's a starting point. As you work, you'll want to expand it.
The fastest way to update CLAUDE.md or AGENTS.md is to ask your agent to do it.
Treat it like a living doc. When you change how the workspace is organized, or how you work, update the file.
If you share the workspace folder with your team, you share CLAUDE.md and AGENTS.md with them too. Everyone's agent reads the same context.
For shared workspaces: