Project instructions

PERIDOT.md: a file in your project folder with instructions the agent always follows, in the desktop app and the CLI.

Put a file named PERIDOT.md in the root of your project folder and write in it what the agent should always keep in mind: how to build and test the project, the conventions you follow, what it must never touch. Peridot sends the file with every request of the coding agent, so you don't have to repeat yourself in every chat.

It works in Peridot Code (the desktop app) and in the CLI. The web chat and the mobile apps have no project folder, so they don't use it.

Creating the file#

Create PERIDOT.md next to your other project files, in the folder you opened in the desktop app or started peridot in. Write plain text or Markdown, in any language:

markdown

# Instructions for Peridot

- This is a Bun project: use `bun install` and `bun run test`, never npm.
- Code style: TypeScript, 2 spaces, no semicolons.
- Run the tests after every change and fix what you broke.
- Never edit files in `migrations/` that are already released. Add a new one.
- Answer in Polish.

You can also ask the agent to write it: "Look at this project and create a PERIDOT.md with the commands and conventions you find."

Tip

Keep it short and concrete. Commands, rules and the things the agent gets wrong without being told work best. The file is not the place for a long description of the whole project: the agent can read the code itself.

How it is used#

The file is read when you send a message. Saved changes count from your next message, with no restart.
Its text is added to the agent's instructions for every step of the task, so it is not forgotten in long tasks.
Your AI team follows it too: every bot gets the same project instructions.
What you write in the chat comes first. If a message asks for something else than PERIDOT.md, the agent follows the message. The safety rules always apply: the agent stays inside the project folder and asks before edits and commands as set in Tools and approvals, whatever the file says.

Limits#


Name and place	Exactly `PERIDOT.md`, in the root of the project folder. Files in subfolders are not read automatically.
Size	Files over 400 KB are ignored. Only the first 20,000 characters are used, the rest is cut.
Usage	The text counts toward the size of every request, and so toward your usage. A short file costs little.
Format	A text file (UTF-8). A binary file is ignored.

If the file is missing, empty or can't be read, the agent works as usual, without project instructions.

Should I commit it?#

Usually yes. PERIDOT.md describes the project, so the whole team, and everyone who opens the project in Peridot, gets the same instructions. Don't put secrets (passwords, keys, tokens) in it: it is sent to the model with every request.

For API clients#

Clients of the agent protocol send the file's text in the instructions field of POST /chat/agent. The server cuts it to 20,000 characters and adds it to the system prompt of the lead and of every bot.

← Cowork Using the team in the CLI →