Refinar

AGENTS.md generator that reads your repository

Paste a public GitHub repository. The generator works out how the project installs, runs and checks itself, using the same detection Refinar uses to start an app, and drafts a short AGENTS.md from what it finds, plus a CLAUDE.md that imports it. No forms to fill in. Free, no signup.

Public repositories only. It reads file names and dependency manifests, and only the names from an example env file. Nothing is written to GitHub.

What goes in the file

Each part comes from the repository itself. Nothing is padded to look thorough.

Stack
The framework, the folder the app lives in, the package manager and, in a monorepo, where to install from
Commands
Install, run and build, as the commands that actually start the app, not whatever the README last said
Before you finish
The typecheck, lint and test scripts the repository has, in the order to run them, or a plain note that it has none
Environment
Variable names from an example env file such as .env.example. Names only, never values
Rules
A few that follow from the repository: migrations, lockfiles, the formatter, CI files, payments
CLAUDE.md
One line that imports AGENTS.md, so Claude Code and every other agent read the same instructions

AGENTS.md example

What the generator drafts for a Next.js app on pnpm that uses Supabase and Stripe. Yours will follow your repository.

# AGENTS.md

Bookings for a padel club.

## Stack
- Next.js with TypeScript, in the repository root.
- Package manager: pnpm. Use it for every install and never add a second lockfile.
- Talks to: Supabase, Stripe.

## Commands
- Install: `pnpm install`
- Run the app: `pnpm run dev`
- Production build: `pnpm run build`

## Before you finish
- Run `pnpm run typecheck`, then `pnpm run lint`, then `pnpm run test --run` and fix what they report.
- Keep the change to what was asked; mention anything else you noticed instead of fixing it.

## Environment
- The app expects these variables (names from `.env.example`): `NEXT_PUBLIC_SUPABASE_URL`, `STRIPE_SECRET_KEY`.

## Rules
- Don't edit `pnpm-lock.yaml` by hand; let the package manager update it.
- Database changes go in a new file under `supabase/migrations/`. Never edit one that has already run.
- Real secrets live in local env files that aren't committed. Never print, log or commit their values.
- Anything touching payments or webhooks needs a human review before it ships.

AGENTS.md template

Prefer to write it yourself? Fill in the blanks and delete any line that doesn't apply. The rules are the part only your team can write.

# AGENTS.md

One sentence on what this project is.

## Commands
- Install:
- Run the app:
- Before you finish, run:

## Rules
- Use <package manager>. Never <the others>.
- Don't edit <generated folder>; run <command> instead.
- Database changes go in <where>. Never edit an old migration.
- Secrets live in <file>, which isn't committed. Never print or commit them.
- <Anything a new developer gets wrong in their first week.>

CLAUDE.md example

Keep one set of instructions: import AGENTS.md on the first line and put only Claude-specific notes underneath.

@AGENTS.md

## Claude Code only
- Use plan mode for anything that touches more than three files.

What makes a good AGENTS.md

It holds what an agent can't work out by reading the code. An agent finds your components and your folder layout in seconds. It can't know that the app must be started with pnpm, that the generated folder is rebuilt by a script, or that an old migration must never be edited. Those are the lines that save a wasted run.

It is short. Codex stops reading once all its AGENTS.md files together reach 32 KiB, Devin takes the first 16 KiB, and Anthropic suggests keeping a CLAUDE.md under 200 lines. Style rules a linter already enforces, and a tour of the folders, are better left out.

Someone on the team has read it. A drafted file is a starting point. The rules that matter most, the ones about what not to touch, come from people who have been bitten by them. For how the file compares with CLAUDE.md, see AGENTS.md vs CLAUDE.md.

Limits

Worth reading before you commit the result.

  • It reads file names, dependency manifests such as package.json, and the variable names in an example env file. It doesn't read your source code, so it can't know your naming habits or the parts of the codebase people avoid. Those are the lines worth adding by hand.
  • Commands come from the same detection Refinar uses to start an app, which covers Node, Python, PHP, Ruby, Go, Rust, Deno and Flutter projects. An unusual setup can still be read wrong, so try the commands once before you commit the file.
  • Very large repositories are listed by GitHub only in part. The result says when that happened.
  • Private repositories aren't read here. Refinar reads them once you connect GitHub.
  • Each visitor can generate a few files a minute. A repository that hasn't changed returns the same draft for an hour.

About AGENTS.md

What is AGENTS.md?

A plain Markdown file at the root of a repository that tells coding agents how to work in it: the commands to install, run and test, and the rules a newcomer would get wrong. The agents.md site calls it a README for agents. Codex, Cursor, GitHub Copilot's cloud agent, Jules, Amp, Windsurf and others read it, and the format is now looked after by the Agentic AI Foundation at the Linux Foundation.

Does Claude Code read AGENTS.md?

Since version 2.1.277, released on 18 September 2026, yes, but only in a project that has no CLAUDE.md. If there is a CLAUDE.md, Claude Code reads that instead. That's why the generator also gives you a CLAUDE.md whose first line is @AGENTS.md: it imports the same instructions and works on every version.

How is this different from other AGENTS.md generators?

Most ask you to type your commands and rules into a form and hand them back as Markdown. This one reads the repository and works the commands out, using the detection Refinar runs before it starts an app in the cloud, so the install and run lines are the ones that actually work. It also keeps the file short on purpose.

Why is the file so short?

Because more isn't better here. A 2026 study from ETH Zurich found that context files generally added cost without making agents more successful, that files written by a model did worst, and that hand-written ones did better. The draft holds only what an agent can't easily work out from the code, and leaves room for your own rules.

Is it free? Is anything stored?

It is free with no signup. It reads public data from GitHub and doesn't write to the repository. The draft is cached for an hour against the repository's last push, so the same repository returns the same file without being read again. No model is involved, so nothing from the repository is sent to an AI provider.

Where should the file go?

At the root of the repository, named AGENTS.md exactly. A monorepo can add more in package folders: Codex reads every file from the root down to the folder it's working in, and GitHub Copilot uses the nearest one. Commit CLAUDE.md next to it if anyone uses Claude Code.

Other free tools

Got a change that's been waiting for weeks? Bring it to a call.

Book a call