Bring your agent.

effortless new writes AGENTS.md into the project: 99 lines naming the mistakes agents make here, which part of the reference each task needs, and the commands that check the work. The 169 KiB reference stays in the binary, so the agent reads the version it runs, one topic at a time, instead of loading all of it into every session.

Plain text AGENTS.md Open in Claude Open in ChatGPT

Set up your agent

Claude Code

Reads CLAUDE.md, not AGENTS.md. Point one at the other, once, in the project folder:

ln -s AGENTS.md CLAUDE.md

Or a CLAUDE.md containing @AGENTS.md, with Claude-specific lines below it.

Codex

Reads AGENTS.md from the repository root. Nothing to add.

Cursor

Reads AGENTS.md natively, as an alternative to .cursor/rules. Nothing to add.

Copilot, Zed, Windsurf, Amp, opencode, Jules, goose, Devin

All read AGENTS.md from the project root. Nothing to add.

Gemini CLI and Aider

Read AGENTS.md once a setting names it. For Gemini CLI, in .gemini/settings.json:

{ "context": { "fileName": "AGENTS.md" } }

For Aider, in .aider.conf.yml:

read: AGENTS.md

The reference, by topic

An agent with a shell reads the part a task needs. A word that matches no heading searches the paragraphs instead, so a name the agent is unsure of comes back with where it is used.

effortless docs --list
effortless docs eql
effortless docs ui-combobox
effortless docs --search sync_rows

A chat without a shell

It cannot run effortless docs, so give it the whole reference. The buttons above open Claude or ChatGPT with that prompt filled in.

https://effortless.run/llms.txt

When the agent guesses

Styling is Tailwind and the parts look like shadcn/ui, which agents already write. The rest is new to every model, so an agent writes React and Svelte by habit. A wrong guess is an error that names the fix and the section to read, not a bug that surfaces later.

A function the module does not have

$ effortless eval 'return eql.cout "select events"'
effortless.eql has no field 'cout' (did you mean 'count'?);
see effortless docs eql

Svelte syntax in a page

$ effortless check
routes/index.x.html:12: [markup] {#if !e…} is another
template language's block: put @if={…} or @each={…} on the element

1 issue found
Read before fixing: effortless docs markup

Prompts that work

Say what the page should do and who sees it, and end with the checks. Name files and commands when you know them; the agent finds the rest in AGENTS.md.

A new project

Install Effortless from https://effortless.run, create a project called commons, link AGENTS.md to CLAUDE.md, and start the server. Tell me the address to open.

A page that matches a design

Make /events match the attached screenshot: the same spacing, colors and type sizes, in Tailwind classes, with effortless-ui's parts where it has them. Keep the data it shows now, and make it work at phone width. Run effortless check before you finish.

Organizers only

Add a memberships table that links users to groups with a role, member or organizer. Only a group's organizers can open /events/new and post its events; everyone else gets a 403. Add a test for both, and run effortless check and effortless test.

A feature, end to end

Add a deals table to app/schema/schema.lua: title (required), stage as an enum lead/qualified/proposal/won/lost, amount, and owner_id as the owner column. Build /deals as a list of the signed-in user's deals with an add form, and tests/deals_test.lua with one success and one failure case. Run effortless check and effortless test before you finish.

A query, in the query language

Read effortless docs eql first. Then replace the Lua loop in routes/reports/reports.lua with one EQL statement that returns each company with its count of open deals and the sum of their amounts, largest first. Verify with effortless request GET /reports --data --as 1.

An island

Read effortless docs inlay first. Turn the deal list on /deals into an island in app/components/deal-list.x.html that changes a deal's stage with inlay.post and shows the 422 error it gets back. The actions in routes/deals/deals.lua answer with response.json. Add the JSON cases to tests/deals_test.lua and run effortless check and effortless test.

A bug, reproduced first

POST /contacts returns 403 from the browser. Reproduce it with effortless request POST /contacts -d action=add -d name=Test --as 1, read the error it prints, fix the cause, and add the failing case to tests/contacts_test.lua.