CLAUDE.md and AGENTS.md

CLAUDE.md and AGENTS.md can tell an agent who you are, what the workspace is for, and how you work. Automatic loading depends on the agent.

• CLAUDE.md is read by Claude Code.
• AGENTS.md is read by Codex.
• Palette Desktop does not currently guarantee automatic AGENTS.md loading for Gemini, Mistral Vibe, or Palette's own agent. Mention the file explicitly when those agents need it.

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.

Where they live

In the root of your workspace folder, alongside your top-level folders.

your-workspace/
├── CLAUDE.md
├── AGENTS.md
├── accounts/
├── playbooks/
└── ...

Keep the file for the agents you use. If everyone uses Claude Code, CLAUDE.md is enough. If you use Codex too, keep AGENTS.md as well. The simplest approach is to share the relevant sections and update both together.

What to put in them

Claude Code or Codex reads its supported instruction file at the start of a session. Keep it scannable, not exhaustive.

A good CLAUDE.md or AGENTS.md covers:

• Who you are. Your name, role, what you do day to day.
• What this workspace is. The purpose of the folder, what kinds of work happen here.
• How you work. Conventions to follow, tools you use, things to avoid.
• Where to look. A short map of the folders inside this workspace, so the agent knows where things live.
• What's in flight. Active projects or context worth flagging up front.

What to leave out:

• Long histories or wikis. The agent can read other files when it needs to.
• Information that lives elsewhere and changes often (live metrics, calendar, and the like).
• Anything sensitive you wouldn't want every chat to see.

How the starting guide writes the first one

When you turn on the starting guide for a new folder, Palette writes an initial CLAUDE.md based on:

• What you tell the guide about yourself
• What the workspace is for
• The first workflow or starter skill you set up

It is a starting point. If your team also uses agents that read AGENTS.md, create that file separately and keep the relevant shared instructions aligned.

Keeping it sharp

The fastest way to update CLAUDE.md or AGENTS.md is to ask your agent to do it.

• "Update CLAUDE.md to add the new accounts folder."
• "Reflect this decision in AGENTS.md."
• "Check CLAUDE.md against how I actually work. Anything out of date?"

Treat it like a living doc. When you change how the workspace is organized, or how you work, update the file.

Sharing with your team

If you share the workspace folder with your team, you share CLAUDE.md and AGENTS.md with them too. Claude Code and Codex can then read the same supported instructions; other agents need an explicit pointer when automatic loading is not guaranteed.

For shared workspaces:

• Keep the file focused on the team and the work, not on individual preferences.
• Put personal preferences (your voice, how you like things drafted) in a separate file the agent can read.
• Update it together, the same way you'd update any shared doc.

Related

• Agents, the agents that read these files
• Working with README and index files, the same idea one level down, inside each folder
• Structuring your workspace, how to lay out folders so agents can navigate them
• Workspaces, the folder these files live in
• Quick start, the starting guide that writes the first version