A Stray AGENTS.md Can Steer Your Agent: Check What It Loads First

On 22 October, the security firm Forever Security published a report about a file it found on a customer's machine: an AGENTS.md sitting in ~/Downloads, written to look like ordinary engineering notes. The customer had started OpenAI Codex in that folder. Codex read the file as project guidance and began installing function-color, a known malicious npm package, before Forever's tooling stopped it.

The researchers then reran the real file inside an isolated VM. In their tests, Codex carried out the payload in more than 90% of attempts, and the file had it add a server to ~/.codex/config.toml, the machine-wide config, so the damage didn't stay in Downloads. They also built a CLAUDE.md variant against Claude Code, which they describe as much harder to fool; it followed through about half the time in their testing.

Their conclusion is the part worth keeping: nothing here is a bug to patch. An agent that follows the instruction file in its folder is doing what it was built to do. So the defence is on you, and it starts with knowing which files your agent loads before you press Enter.

Why the folder you start in matters

Instruction files like AGENTS.md and CLAUDE.md aren't opened on request. They're loaded automatically at the start of a session, and the folder you launch from decides which ones. Downloads is a bad place to launch from because, as the report points out, it's the one folder a website can drop a file into without asking.

I covered why these files are context, not a security boundary, in 6 AGENTS.md Mistakes That Make Your Coding Agent Ignore It. This article is about the step before that: discovery.

Where each tool looks

Here's what the official docs say, as of 3 November 2026.

Tool	Global file	Project files
Codex	~/.codex/AGENTS.override.md or AGENTS.md	From the project root (a folder with .git) down to where you started; with no root, only the current folder
Claude Code	~/.claude/CLAUDE.md	CLAUDE.md and CLAUDE.local.md in the current folder and every folder above it; AGENTS.md from those same folders when there's no CLAUDE.md
Cursor	User Rules (Customize → Rules)	AGENTS.md in the project root and subfolders, combined
Gemini CLI	~/.gemini/GEMINI.md	GEMINI.md in workspace folders and their parents

A few details change how you should read that table.

Codex checks each folder for AGENTS.override.md, then AGENTS.md, then any names you added in project_doc_fallback_filenames, and takes at most one file per folder (Codex AGENTS.md docs). If it can't find a project root, it only checks the folder you're in. That's exactly the Downloads case: not a Git repo, so the file in Downloads is the project file. Forever also notes that Codex only obeys an AGENTS.md in a project it trusts, and that once you've worked in Downloads before, it qualifies.

Claude Code walks up, not just down. Start it in foo/bar/ and it loads foo/bar/CLAUDE.md and foo/CLAUDE.md at launch, plus files in subfolders later, once it reads or edits a file there (memory docs). Since v2.1.277 it reads AGENTS.md too, but by default only when there's no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in your folder or above it. In an interactive session it prints a line like no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md, which is worth watching for.

Cursor reads AGENTS.md in the project root and in subfolders, and applies a nested file when you work with files in that folder, with more specific instructions taking precedence (rules docs).

Gemini CLI searches for GEMINI.md in your workspace folders and their parents, and also scans a folder and its ancestors when a tool touches a file there (GEMINI.md docs).

The common thread: a file you never opened can end up in the agent's context just because of where it sits relative to where you started.

A 5-step check before you run the agent

1. Start from the project folder, never Downloads or home

Open a terminal in the repository you mean to work on. Claude Code's own security docs push in the same direction: if you start it directly in your home directory, trust is held for that session only and the prompt comes back every launch, and the docs suggest starting from a project subfolder instead. For Downloads, Forever's advice is simply not to start any agent there.

2. List the instruction files it could load

Before launching, see what's above, around and below you. Here's a small bash sketch that lists the usual filenames; adapt the list to the tools you use:

#!/usr/bin/env bash
# List instruction files a coding agent could load if started here.
names="AGENTS.md AGENTS.override.md CLAUDE.md CLAUDE.local.md GEMINI.md .claude/CLAUDE.md .claude/AGENTS.md"

# This folder and every folder above it
dir="$PWD"
while :; do
  for n in $names; do [ -f "$dir/$n" ] && echo "here/above: $dir/$n"; done
  [ "$dir" = / ] && break
  dir="$(dirname "$dir")"
done

# Global files in your home directory
for f in ~/.codex/AGENTS.md ~/.codex/AGENTS.override.md ~/.claude/CLAUDE.md ~/.gemini/GEMINI.md; do
  [ -f "$f" ] && echo "global: $f"
done

# Subfolders (loaded later, when the agent works there)
find . -mindepth 2 -name node_modules -prune -o -type f \
  \( -name AGENTS.md -o -name AGENTS.override.md -o -name CLAUDE.md \
     -o -name CLAUDE.local.md -o -name GEMINI.md \) -print | sed 's/^/below: /'

If you use Codex fallback names, add them to the list. Anything you don't recognise is the thing to read next.

3. Read the files you didn't write

You don't need to audit every line of your own AGENTS.md. You do need to read a file that came with a fresh clone, a download or a teammate's branch. The file Forever captured was about 13 KB of bland notes, with the attack in one "Local developer environment" section near the end, so skimming the top isn't enough. A quick search for the risky parts helps:

grep -n -i -E "mcp_servers|config\.toml|settings\.json|BASE_URL|dangerously|bypass|npx|npm install|curl|launchctl" AGENTS.md CLAUDE.md 2>/dev/null

None of those words is proof of anything. They're the places where an instruction file stops describing your project and starts telling the agent to change its own setup or fetch something.

4. Confirm what actually loaded

Once you've read the files, check that the agent sees what you expect:

• Claude Code: watch for the AGENTS.md loaded: line, or run /context and look under Memory files.
• Codex: the docs suggest codex --ask-for-approval never "Summarize the current instructions." from the repo root, or opting into a plaintext log with codex -c log_dir=./.codex-log and checking codex-tui.log.

Treat this as confirmation, not your first line of defence. Asking an agent to summarise its instructions still means starting it with those instructions loaded.

If ancestor files keep getting in the way, Claude Code's claudeMdExcludes setting skips specific CLAUDE.md files by path or glob, and Codex's project_root_markers controls what counts as a project root.

5. Keep the brakes on, and check the agent's own config

Leave sandboxes and approvals on. Codex's approvals and security docs say the CLI and IDE extension default to no network access and writes limited to the active workspace; for chat or planning without changes, switch to read-only with /permissions. Be very suspicious of any instruction that asks for --dangerously-bypass-approvals-and-sandbox, which is the flag the captured file had the model use.

Then look where the attack actually landed. Forever's checklist: an unexpected [mcp_servers.*] block or a changed chatgpt_base_url in ~/.codex/config.toml, and an ANTHROPIC_BASE_URL, proxy or other endpoint you didn't set in a project's .claude/settings.json. If you find one, they advise assuming the token leaked and rotating it, and treating any machine with function-color installed as compromised.

Checklist

1. Don't start any coding agent in ~/Downloads or directly in your home folder.
2. Know the discovery rule for each tool you use: Codex goes from the Git root down, Claude Code goes up from where you start.
3. List instruction files above, in and below your folder before launching.
4. Read every instruction file you didn't write, all the way to the end.
5. Search for config edits, base URLs, bypass flags and installs in those files.
6. Confirm what loaded with /context or the Codex log.
7. Keep sandbox and approval defaults on.
8. Check ~/.codex/config.toml and .claude/settings.json for entries you didn't add.

Where to go next

If you want to write a good AGENTS.md of your own, the free AGENTS.md Quick-Start Cheat Sheet covers what belongs in the file, what to leave out, the one-line test for each line, and cross-tool use including the Claude Code symlink, in 6 pages.

For the full picture, AGENTS.md: The Complete Guide to the Cross-Tool Agent Standard spends 42 pages on how agents find and load the file, the monorepo hierarchy with nearest-file precedence, cross-tool portability, the common mistakes and a 30-day adoption plan.

This article was written with the assistance of AI and reviewed by the author.