BENCHY.md

What it is

BENCHY.md is a project's brief: one plain Markdown file at the root of the folder tree. It says what the project is, what has been decided so far, and what the project works with. Every project has one — it is made with the project, and the project page shows it in its own panel rather than as a row in the file list. It can't be renamed, moved or thrown away; you edit it instead.

A new project starts with its name, its description, and the headings to fill in:

# Wall bracket

A bracket that holds a 12 mm dowel under a shelf.

## Use

## Decisions

Why a file

The brief could have been a settings screen. It is a file on purpose, and everything else on this page follows from that:

• It travels. Download the project, copy it, or open the folder on your Mac in Benchy Desktop, and the brief comes with it.
• Anything reads it. Markdown needs no client and no account. Benchy reads it, and so do Claude Code, Codex, Cursor and whatever you write yourself.
• It has a history. Every change is a version of the file, and each version names who wrote it and which app it came through.
• It is one place. The material, the tolerance and the thing you argued about last week live in the project, not in a chat someone has to find again.

Who reads it, and when

What goes in it

Most of the file is yours. Write plain Markdown, for a person and an agent to read, and Benchy takes all of it as context. Keep it short: a brief that outgrows a screen or two gets shown to Benchy in part, and a brief nobody rereads stops being true. Move detail into a doc or a skill and name it here.

Two headings are worth keeping, and one of them tools read by name:

The headings that earn their place in most projects after those:

• Decisions — the material, the tolerances, the printer, everything already settled. This is the section that saves the most time.
• 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

# Wall bracket

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

## Use
- Brand: @olive-studio
- Skills: /plan-a-print-project, /print-prep
- Plugins: Print planning

## 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 on the project page, in the panel beside the files, or in your own editor when Desktop has the folder open on your Mac.
• Anyone who can edit the project can change it, including a guest invited to edit it. Every version names who wrote it and which app it came through, and the file keeps its versions like any other. See Files and versions.
• Uploading a BENCHY.md to the top of the project makes a new version of the brief rather than a second file.
• Two writers never overwrite each other. A write is made on top of the version its author read; if the brief moved in between, the write is refused, your text is kept in front of you, and you write it again on top of the new version.
• An API key or connected app can't upload the file. It writes the brief with project_brief_write, which follows the same rule.
• Ask Benchy to keep it up to date — “put that in BENCHY.md” once something is settled — and it shows you the whole new text to approve before saving it.

Sharing and secrets

A share link to a project shows its BENCHY.md like any other file in it, and the project page says so beside the brief. Anyone you send that link to reads the brief, so 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, CLAUDE.md and DESIGN.md

These answer different questions, and they sit side by side in the same folder without clashing:

Benchy reads BENCHY.md. It does not read an AGENTS.md or CLAUDE.md sitting in your project — if something in one should govern the work here, put it in the brief. Your own agents go on following their own files as usual.

Starters

A Starter ships a BENCHY.md. It is how a ready-made project explains itself: what it is for, how to use it, and the skills, Elements and plugins it relies on. When you use a Starter, that brief becomes the new project's brief, and it is yours to change from then on.