Coredence

Guide

AGENTS.md: one instruction file for many coding agents

Every coding agent wanted its own instruction file. AGENTS.md is the attempt to have one — a README written for agents instead of people.

Ahmet Karaca ·

What it is

AGENTS.md is an open format: a Markdown file at the root of a repository that tells coding agents how to work on it — how to build and test, the conventions to keep, what not to touch. It is stewarded by the Agentic AI Foundation under the Linux Foundation, and agents.md lists more than twenty-five agents that read it, among them OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI and Jules.

There is no required structure. Plain headings and short lists work best, because the agent reads the whole file every time.

Nested files, and the one that is yours

  • In a monorepo, each package can have its own AGENTS.md. The file closest to what is being edited wins, and what you type in the chat overrides all of them.
  • Codex reads files from the repository root down to the current folder and joins them in that order, so a closer file has the last word. It stops adding files at 32 KiB by default.
  • Codex also reads a personal file before any project one: ~/.codex/AGENTS.md in your home folder. That is the place for how you work, as opposed to how the project works.

Claude Code reads its own CLAUDE.md rather than AGENTS.md; a CLAUDE.md can pull another file in with an @ line, which keeps the two from drifting apart.

What is worth writing

Commands the agent cannot guess, conventions it would otherwise break, and the things you keep correcting. A sentence earns its place when it changes what the agent does; a sentence that restates good practice in general costs reading time on every request and changes nothing.

# How I work

- Read the existing file before proposing a new one.
- Ask before deleting files or running destructive commands.
- Plan in a few lines before touching more than three files.
- Write commit messages in the language the repository already uses.

Keep project facts in the repository's file and preferences about yourself in your personal one. A preference committed to a shared repository becomes everyone's rule.

Where Coredence fits

The personal part is the hard part to write, because it comes from months of corrections spread across every assistant you use. Coredence measures it instead: it reads your own sessions, commits and notes, consolidates them into memories about how you work, and keeps each one tied to the traces it grew from. If you turn it on, it writes your mind into ~/.codex/AGENTS.md and refreshes it every cycle, in its own marked section, leaving what you wrote there yourself untouched. Claude Code, Copilot and Gemini get the same mind in their own files.

You can try the real app on a made-up person's mind, in your browser, without installing anything.

Try it in your browser