Open any current software project today and the root directory holds far more than README.md, package.json and .gitignore. More and more often, there is an AGENTS.md as well. It is something like the onboarding folder for coding agents such as OpenAI Codex, Claude Code, GitHub Copilot or Cursor: it describes how the project is built, which conventions apply and what the agent had better leave alone.
That is exactly where the problem lies. Agents take this file seriously – quite literally. On October 22, 2026, security researchers Gal Weizman and Omer Samet of Forever Security described what that means in practice. A single unnoticed download is enough, and your own AI assistant is suddenly working for someone else.
From Chaos to a Standard
As long as AI assistants only completed code, they got by with little context. That changed when they started editing files, running tests and executing commands on their own. An agent that doesn't know a project's architecture, build commands and conventions writes code that has to be painstakingly reined in afterwards.
So at first, every vendor invented its own format. Anthropic went with CLAUDE.md, Cursor with .cursorrules (later .cursor/rules), and other tools wanted .clinerules, GEMINI.md or .github/copilot-instructions.md. In teams where not everyone uses the same tool, five or six files with almost identical content quickly piled up in the repo. By the third change at the latest, they no longer matched.
AGENTS.md is the answer to this mess. The format was created in 2025 as a joint project of OpenAI, Google, Cursor, Amp and Factory and is now maintained by the Agentic AI Foundation under the umbrella of the Linux Foundation. Codex, Cursor, GitHub Copilot, Windsurf and Zed read the file. Since version 2.1.277 of September 18, 2026, Claude Code uses it as well, provided the project contains no CLAUDE.md. Teams that maintain both simply include the AGENTS.md in their CLAUDE.md via @AGENTS.md.
The basic idea fits in one sentence: README.md is for humans, AGENTS.md is for machines.
How the File Steers the Agent
Technically, there is nothing special about AGENTS.md. It is plain Markdown with no prescribed schema. What makes the file interesting is what the agent does with it.
When you start a coding agent in a directory, it looks for an AGENTS.md there and loads its entire content into its context before you have even asked the first question. Monorepos may contain several of these files, such as /frontend/AGENTS.md and /backend/AGENTS.md. The file in the root then sets the global rules, and for the file the agent is currently working on, the nearest AGENTS.md usually takes precedence.
The crucial difference from ordinary documentation is that the agent doesn't just read it – it acts on it. If the file says “Run npm run test:unit after every change and fix errors on your own”, that exact command runs on the developer's machine.
This is what a typical AGENTS.md looks like:
# Project Context & Agent Rules ## Build & Test Commands - Run tests via `pnpm test:unit` (never run the full suite without asking). - Linter check: `pnpm lint --fix` before finishing any task. ## Architecture & Conventions - State management uses Zustand, do not introduce Redux. - All database queries must go through `/src/db/repositories`. - Write strict TypeScript; `any` is forbidden.
Why It Pays to Maintain It
A well-maintained AGENTS.md often decides whether an agent behaves like an experienced colleague or whether you are constantly cleaning up after it. Without clear guidelines, language models like to reach for outdated library versions or mix in patterns that have no place in the project. With the stack spelled out in black and white, this happens much less often.
There is also a very practical effect. The agent doesn't have to spend every session figuring out with grep and find how to run the tests or where the API routes live. That saves time and tokens. And if it knows the exact commands for linting, type checking and tests, it can check and fix its own code before a human takes a look.
The Flip Side: When the File Becomes a Weapon
A program that reads a text file and executes the instructions in it blurs the line between documentation and code. Weizman and Samet sum it up in a short formula: Markdown is the new executable.
They didn't find the problem in a lab. Their software had stopped a coding agent on a customer's machine just as it was about to install the npm package function-color, a known malicious package. What was strange was where the command came from. Not from a dependency, not from a repository, but from an AGENTS.md in the Downloads folder. Nobody knew how it had got there.
How the Attack Works
The attack chain combines two things that are each completely harmless on their own.
First, browsers save downloads to ~/Downloads by default without asking. A rigged website can therefore quietly drop an inconspicuous text file called AGENTS.md there. No human even has to be sitting at the screen. According to Forever, around a quarter of all agent sessions open a real browser, so the agent can pick up the file itself.
Second, many developers sooner or later start their agent directly in the Downloads folder – to take a quick look at an archive, check a script or try out a small tool. In Forever's telemetry, this happens at about half of its customers.
If you then type codex in ~/Downloads and ask any harmless question, the agent treats the planted file like ordinary project context. Codex does have a safeguard and only follows an AGENTS.md in folders you trust. But anyone who has worked there before has long since removed that hurdle themselves.
What the File Does
The AGENTS.md they found was a roughly 13 KB, deliberately boring document of “Engineering Work Guidelines”. The actual attack, a classic indirect prompt injection, sits in a section near the end and poses as routine setup for project tools.
With Codex, this section gets the agent to add an extra MCP server to its global configuration ~/.codex/config.toml before tackling the actual task. Through this entry, function-color is installed and executed. To keep the sandbox's network block out of the way, the file has Codex start a second instance with the --dangerously-bypass-approvals-and-sandbox flag. In the researchers' tests, Codex executed the malware in more than 90% of attempts. What makes it particularly nasty is that the change applies to the whole machine. From then on, every Codex session loads the attacker's server, no matter which project.
Claude Code was much harder to fool. For this case, the researchers wrote a rigged CLAUDE.md themselves, modeled on the real file. It is designed to get Claude to set the ANTHROPIC_BASE_URL variable in .claude/settings.json to an attacker-controlled server, disguised as an internal company gateway. Claude normally asks for approval before this kind of write and often rejects suspicious changes on its own. Even so, the long, inconspicuous packaging got through in about half of the attempts. After that, all API requests run through the foreign server, including the OAuth token. That is enough for an account takeover without a single line of code having to run. And because the server can pose as the model, from the next session on it slips Claude tool calls that are then executed directly on the machine.
Why There Is No Patch for This
The really tricky part: there is no bug that OpenAI or Anthropic could simply fix. An agent that follows the AGENTS.md in its working directory is doing exactly what it was built to do. The researchers compare it to phishing. When a browser displays a fake banking page, it is also just doing its job.
For decades, a file in the Downloads folder was considered harmless as long as nobody double-clicked it and ignored the operating system's warnings (such as Gatekeeper on macOS). Agents break this assumption because they read text and translate it into shell commands themselves. The same risk, by the way, applies to any third-party repository you clone from GitHub that contains a manipulated AGENTS.md.
What Developers and Teams Can Do Now
Because the gap opens at the seam between browser and agent, what helps most is discipline about the working directory, complemented by a few technical guardrails.
- Agents belong neither in the Downloads folder nor directly in the home directory. Downloaded files should first be moved to a separate, clean folder.
- Third-party instruction files should be read before an agent works with them.
AGENTS.md,CLAUDE.mdor.cursor/rulesin a freshly cloned repo deserve the same skepticism as a Makefile or apostinstallscript inpackage.json. - Sandbox and confirmation prompts are best left switched on, especially for changes outside the project folder and for network or package manager commands such as
npm installorcurl. If a project asks you to run the agent in YOLO mode without confirmations, be suspicious. - It pays to check the agent configuration regularly. In
~/.codex/config.toml, unknown[mcp_servers]entries or a modifiedchatgpt_base_urlare suspicious; in.claude/settings.json, anANTHROPIC_BASE_URLor a proxy that nobody set on purpose. - Anyone who finds something like this should assume the token has leaked and replace it. If
function-color(since removed from npm) shows up among a machine's installations, treat the machine as compromised.
The Bottom Line
AGENTS.md is not going away – and that's a good thing. The file solves a real problem and is what makes agents reliable collaborators in larger codebases in the first place. But the case shows that our habits have to change. If a sentence in natural language is enough to make a machine execute code, then every text file an agent reads is essentially executable. Prompt context therefore deserves the same scrutiny as source code.