--- title: "Your agent hasn't read your folder" description: "Opening a folder in Claude Code or Codex doesn't put its files in the model's head. It starts with almost nothing and has to go and read. That's a good thing, and it makes AGENTS.md the most important file you'll write." date: 2026-10-10 language: en canonical: https://gduv.club/articles/agent-folder-context source: gduv.club --- When people start working with an agent inside a folder, they assume it knows everything in that folder. Your notes, your client files, the process you wrote down last month. It's all right there, so surely it read it. It didn't. When you open a new conversation, **the agent knows almost nothing** about what's in your folder. It knows the folder exists and that it can look inside. ## What it actually has when you start At the first message, the model receives a short list of things: - the instructions the app wrote for it (how to behave, how to use each tool), - the descriptions of the tools it can call, - one file of yours, if you've written it: `AGENTS.md`, - and your message. **That's the whole picture**. Everything else in the folder, it has to find: list the files, search them, open the ones that look relevant. Each of those is a tool call, the same way it would search the web. I show this in my workshop with a folder of 20 task files. In a new conversation, I ask what task 10 is about. It doesn't answer straight away. It searches the folder, finds the file, reads it, and then answers. It works, but **it had to go and get it**. | Frame | Total | What it holds | | :--- | :--- | ---: | | Your first message | 7,625 tokens | app instructions, tool descriptions, AGENTS.md, your question | | It searches the folder | 7,845 tokens | app instructions (cached), tool descriptions (cached), AGENTS.md (cached), your question (cached), search result | | It opens one file | 8,395 tokens | app instructions (cached), tool descriptions (cached), AGENTS.md (cached), your question (cached), search result (cached), task-10.md | _Sizes are illustrative and change with every app. The point is what is missing: of a folder of 20 task files, only the one it opened ever reaches the model._ ## Why that's a good thing It's frustrating at first. It would be convenient if the agent simply knew everything. But think about what that would cost. Every message you send carries everything the model receives: the app's instructions, the tool descriptions, your files, the whole conversation so far. If your folder were loaded every time, you'd pay for all of it on every message, and the model would have to find your one relevant paragraph in the middle of everything else. Recent models can take in a lot, up to about a million tokens for some. More room doesn't make everything useful though. Extra text is noise, and the model can get confused by it the same way you would. I try to make sure every token in there has a reason to be there. So the agent not knowing your folder is what gives you control. You decide what it always knows, and you organise the rest so it can find things fast. ## AGENTS.md is your one guaranteed slot `AGENTS.md` is a plain text file at the root of your folder. The app reads it at the start of every conversation and puts it in the model's context, next to its own instructions. It's the one place where something is always remembered. The test I use: open a new conversation and ask "who am I?". If your role is in `AGENTS.md`, it answers straight away, without opening a single file. Same with a rule like "always answer in three bullet points". Put it there, and every answer follows it. - **You:** Who am I? - **Agent:** You're Alex Martin, content marketing manager at Northwind. You own the blog, the newsletter and the company's LinkedIn. [1] - **You:** What's task 10 about? - **Tool call:** `search_files` (query: "task 10") [2] - **Tool call:** `read_file` (tasks/to-do/T10-webinar.md) - **Agent:** Task 10 is the clinic owners webinar: pick a date, invite two customers as speakers, and prepare the registration page. [3] . **Answered straight away**: No tool call. Who you are is in AGENTS.md, which was loaded before you asked. . **Not in AGENTS.md: it has to look**: A search, then a file read. Two tool calls before it can answer. . **The answer, from the file it opened**: It only knows task 10 because it went and read it. _Same conversation, two questions. The first answer comes from AGENTS.md. The second one has to be fetched._ Claude Code used to only read a file called `CLAUDE.md`. Recent versions read `AGENTS.md` too, which is the name Codex and most other tools use, so one file works for all of them. If yours doesn't seem to be picked up, ask the agent which instructions it loaded. I wrote more about keeping one file for every tool in [keep your repos harness agnostic](/articles/harness-agnostic-workspaces). ## What goes in it, and what doesn't My rule is simple. If something isn't useful for almost every message, it doesn't belong in `AGENTS.md`. A long one costs tokens on every single message, and it buries the rules that matter. **In AGENTS.md** (useful for most messages) - Who you are: your role, your team - The company, in two or three lines - Working rules: "say clearly when you are not sure", "explain how you got a number" - How you want answers: one-line conclusion first, then details - A map of the folder - A table of skills, with where to find each one - A table of tools, with when to use each one **In other files** (read when the task needs them) - The full company description and product details - Client and project information - How you write a LinkedIn post, or run a client report - Meeting notes, exports, drafts - Anything you only need once a month _AGENTS.md is a one-pager. Its job is to say what's always true and where everything else lives._ The second column isn't less important. It's just **not needed on every message**. `AGENTS.md` points to it ("for anything about a client, read their `information.md` first"), and the agent opens it when the task calls for it. That's what makes a big folder fast to work in. ## Try it Open a new conversation in your folder and ask: "Who am I, and which instructions did you load at the start of this conversation?" If the answer is vague, your `AGENTS.md` is either missing or not saying the things that matter. Ask the agent to help you write it. Then **keep it to one page**.