rei
AGENTS.md8 starsChanged 5 months agoMITView on GitHub
REI is a local-first CLI coding agent (TypeScript, ESM). Its core bet: trust nothing the model says — verify every edit against ground truth. Hold yourself to the same rule. This file is read at runtime as project conventions, so it stays short and actionable. The architecture — modes, the validation pipeline, prompt assembly, the token budget — lives in docs/rei-internals.md. Use that exact typecheck, not -p tsconfig.build.json: the build config EXCLUDES the tests, so it compiles clean while CI…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 31,439 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository3 other files it gives its agents.
- .github/copilot-instructions.mdCopilot instructions
- grill-with-docsSkill
- change-walkthroughSkill
The file
We split this AGENTS.md into the rules it gives an agent
4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 17
Use that exact typecheck, not -p tsconfig.build.json: the build config EXCLUDES the tests, so it compiles clean while CI fails on a test …
- Very specific: line 26
Never invent files, APIs, or behaviour: If a file preview is truncated, read the file with read_files before editing it — do not …
- Distinctive: line 30
One change per edit, and keep call sites in step: If you change a name or a signature, update every caller in the same turn — a …
- Distinctive: line 39
Comments explain WHY, not what: Prefer the reason a line exists — the bug it prevents, the constraint it satisfies — over restating the …
≈ “Common” is an estimate: at least 1 in 5 of the 40,246 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md — working rules for this repo
REI is a local-first CLI coding agent (TypeScript, ESM). Its core bet: trust nothing the model says — verify every edit against ground truth. Hold yourself to the same rule.
This file is read at runtime as project conventions, so it stays short and actionable. The
architecture — modes, the validation pipeline, prompt assembly, the token budget — lives in
docs/rei-internals.md.
Verify before you finish
npx tsc --noEmit # must be clean — the SAME command CI runs
npx vitest run # must be greenUse that exact typecheck, not -p tsconfig.build.json: the build config EXCLUDES the tests, so it
compiles clean while CI fails on a test fixture that no longer matches a type you changed. That has
already happened — adding a required field to a result type passed locally and broke the build.
The typecheck is fully clean today. src/chat/compactor.test.ts used to carry one accepted type
error; it no longer does, so there is no expected failure to look past. Any error you see is yours.
Rules
- Never invent files, APIs, or behaviour. If a file preview is truncated, read the file with
read_filesbefore editing it — do not reconstruct the missing part. - Act, don't narrate. In agent mode, emit the tool call. A turn that describes an edit without applying it accomplished nothing.
- One change per edit, and keep call sites in step. If you change a name or a signature, update every caller in the same turn — a half-applied rename compiles nowhere.
- Source files stay under 400 lines.
src/meta/file-size.test.tsenforces it. Split the module rather than adding to the allowlist. - ESM, always.
package.jsonis"type": "module": useimport/export, and give relative imports the.jsextension (./foo.js), even from a.tsfile. - English in code and in anything the user sees — comments, status lines, error messages.
- Write the regression test first, and prove it fails. A test that passes against the unfixed code proves nothing. Run it before the fix, watch it fail, then fix.
- Comments explain WHY, not what. Prefer the reason a line exists — the bug it prevents, the constraint it satisfies — over restating the code.
- No new
.mdfiles unless asked. Documentation is a deliverable the user requests, not a side effect.
Where things are
| Path | What |
src/agent-mode/ | the native tool-calling loop and its handlers |
src/chat/commands/ | one handler per slash command, registered in registry.ts |
src/config/model-runtime.ts | single source of truth for context window, tokens, thinking |
src/workspace/project-type.ts | project detection and each type's real verify command |
prompts/ | the system prompt, as markdown — modes, formats, skills, roles |
docs/rei-internals.md | how it all fits together |
Per-project conventions come from the workspace's .rei/rules.md, which overrides anything generic
here.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.