BENCHY.md

The project brief: one plain Markdown file at the root of a project that Benchy and your own agents read before they start.

What it is

One plain Markdown file at the root of every project, saying what the project is, what has been decided, and what the work uses. The project page shows it in its own panel beside the files. You can't rename, move or delete it; you edit it. A new project starts with its name, its description, and the headings ## Use and ## Decisions.

Because it is a file, it travels with the project when you download, copy or open it in Benchy Desktop; any agent or tool can read it without an account; and every change is a version naming who wrote it and through which app.

Who reads it, and when

Reader	When
Benchy	On every turn of a chat open on the project, before planning or making anything. See Chats.
Your own agent	When it asks: `project_brief_read` returns the brief and the version it read, and `project_brief_write` saves a new one. See Connect your agent.
Benchy Desktop	From the folder it has open on your Mac, showing it on the project page and giving it to the agent working there. See Benchy Desktop.
Claude Code, Codex and other local agents	Straight off the disk, in a folder you opened in Desktop or a project you downloaded.
Publishing a website	The `Website` section says what to publish and where. See The Website section of BENCHY.md.
Anyone with a share link to the project	In the browser, like any other file in the project. See Sharing.

What goes in it

Plain Markdown, for a person and an agent to read; Benchy takes all of it as context. Keep it short and move detail into a doc or a skill named here.

Section	What it does
`## Website`	Read by name. `Name` is the address, `Output` the folder to publish, and `Build` a note for people — Benchy never runs it. Written for you when you first choose an address. See The Website section of BENCHY.md.
`## Use`	The skills and Elements this work expects, so Benchy and other agents reach for the same ones. See Skills and Elements.
`## Decisions`	The material, tolerances, printer and everything already settled.
`## Open questions`	What nobody has decided, so Benchy asks instead of guessing.
`## How to work here`	Where finished files go, what to name them, what to check before a print.

A complete example

BENCHY.md

# Wall bracket

A bracket that holds a 12 mm dowel under a shelf. It carries a 2 kg load.

## Use
- Style: @olive-studio
- Skills: /plan-a-print-project, /print-prep

## Decisions
- PETG, printed on its side for strength.
- 0.4 mm nozzle; walls at least 1.6 mm.
- Dowel hole 12.4 mm, reamed by hand after printing.

## Open questions
- Whether the shelf screws are M4 or M5. Ask before ordering.

## Website
- Name: olive-prints
- Output: site/
- Build: npm run build

Editing, versions and undo

Edit it in the panel on the project page, or in your own editor when Desktop has the folder open.
Anyone who can edit the project can change it, including an invited guest. It keeps its versions like any other file. See Files and versions.
Uploading a BENCHY.md to the top of the project makes a new version of the brief, not a second file. An API key or connected app can't upload it; it writes with project_brief_write.
Two writers never overwrite each other: a write lands on the version its author read, and if the brief moved in between, Benchy keeps your text and asks you to write it again on the new version.
Ask Benchy to keep it current — “put that in BENCHY.md” — and it shows you the whole new text to approve.

A project share link shows its BENCHY.md, and the project page says so beside the brief. Keep keys, passwords, private addresses and anything under an agreement out of it. Credentials belong in a Connection, which never puts its secret in a file.

AGENTS.md and CLAUDE.md

BENCHY.md says what the project is, what has been decided and what it works with. AGENTS.md and CLAUDE.md tell a particular agent how to behave in the folder. They sit side by side without clashing; Benchy reads only BENCHY.md, so put anything that should govern its work in the brief.