# Instruction files > Which files Nodecode reads into the prompt, where the model finds them, and when an edit takes effect. Source: https://nodecode.ai/docs/instructions Updated: 2026-10-08 ## Files read | File | Applies to | Block | | --- | --- | --- | | `~/.nodecode/AGENTS.md` | Every session, in any folder. | `operator-rules` | | The first project file found | Sessions in that project. | `instructions` | Both ride in the conversation's first user message, ahead of your prompt. Each is a `` block that starts `From :`, `operator-rules` first. The system message holds only the session's folder and the manual's topics. What the model received (~/shop, the turn's first request): ```text system · 1,555 characters · the base prompt, then , user: From /home/you/.nodecode/AGENTS.md: Answer in British English. Commit messages are in the imperative mood. From /home/you/shop/AGENTS.md: # shop Run `pnpm test` before you say a change works. Prices are integer cents, never floats. add a coupon field to checkout ``` A profile has its own home, so it has its own `AGENTS.md`. `nodecode import` writes another agent's rules into `~/.nodecode/AGENTS.md`, one `##` heading per file it read. Chat bots also read `~/.nodecode/SOUL.md`, for their voice. A terminal session does not. The channel cells under [Cells](https://nodecode.ai/cells/browse) say how. ## Project file Nodecode looks in the session's folder for `AGENTS.md`, then `CLAUDE.md`, then `.cursorrules`, and reads the first one there. Finding none, it climbs to the parent folder and looks again. It stops at the first file, at the folder that holds `.git`, at `/`, or after 64 folders. | Rule | Detail | | --- | --- | | One file | Only the first file found is read. | | Git root | The search ends at the folder that holds `.git`. | | No git | The search ends at `/`, or after 64 folders. | | A folder by that name | A folder named `AGENTS.md`, `CLAUDE.md` or `.cursorrules` is passed over. Only a file counts. | | Session in the home | `~/.nodecode/AGENTS.md` is read once, as `instructions`. | Mistakes to avoid: - `AGENTS.md` and `CLAUDE.md` side by side, for both to apply. Only `AGENTS.md` is read. The model gets `From /home/you/shop/AGENTS.md:` and not a line of `CLAUDE.md`. Instead: One file. Link the other to it: `ln -s AGENTS.md CLAUDE.md`. - Rules in `packages/api/AGENTS.md`, the session opened at the repository root. The search climbs from the session's folder. It never looks down. The model gets no `instructions` block. Instead: Open the session in `packages/api`, or put the rules at the root. - An `AGENTS.md` at the root and another in a package. In `packages/api` the package's file is found first. The model gets `From /home/you/mono/packages/api/AGENTS.md:` and none of the root's. Instead: Write what the package needs from the root into the package's own file. - `~/work/AGENTS.md`, for every repository under `~/work`. Each search stops at its repository's `.git`, below `~/work`. The model gets no `instructions` block. Instead: Rules for every session go in `~/.nodecode/AGENTS.md`. - `.cursor/rules/`, `GEMINI.md` or `.github/copilot-instructions.md`. None of them is a name Nodecode looks for. The model gets no `instructions` block. Instead: Keep the rules in `AGENTS.md`. Link the other tools' files to it. ## Size limit The limit is 64.0 KB per file: 65,536 characters. | Case | Result | | --- | --- | | Within the limit | Read whole. | | Over the limit | Refused whole. Nothing is trimmed. No session reads it. | | Blank or unreadable | No block. | The warning names the file, its size and the limit: `~/big/AGENTS.md is not read: 71.2 KB — trim to 64.0 KB` | File over the limit | Who is told | | --- | --- | | A project file | The shell, once per file while the organism runs. | | `~/.nodecode/AGENTS.md` | Every shell, as it attaches, and the model, in its `notices` block. Until the file fits. | The shell in ~/big, one turn in: ```text why does checkout 500? · s-1TVRI3CW ctx 462 · ↑ 462 · ↓ 3 ~/big/AGENTS.md is not read: 71.2 KB × — trim to 64.0 KB why does checkout 500? Read. • nodecode/nodecode-axolotl-cyber (max) · 0.2s completed · ↑462 ↓3 ``` Mistakes to avoid: - Pasting a reference into the file: an OpenAPI dump, a style guide. Past 64.0 KB the whole file is refused, the rules with it. The model gets no `instructions` block. Instead: Keep the rules in the file, and name where the reference lives: `The API reference is docs/openapi.yaml.` ## When edits apply | File | Read | Edit takes effect | | --- | --- | --- | | `~/.nodecode/AGENTS.md`, project file | At the first request of each turn. | At the next turn. | No restart is needed. A conversation keeps the prompt of its first request. A later edit reaches the model at the next turn, as a `` after your message. It lists the lines added (`+`) and removed (`-`), or the whole file when that is shorter. A deleted file reads `(withdrawn)`. After an eviction the prompt is built again from the current files. See [Context](https://nodecode.ai/docs/context). What the model received (~/shop, turn 2, after a line was added): ```text user: now the admin form user: Your standing context changed. Each block below replaces the one of its key you were shown before; one marked changed="lines" lists only the lines added (+) and removed (-). + Never edit files under migrations/ without asking first. ``` What the model received (~/shop, turn 3, after the file was deleted): ```text user: and the receipt user: Your standing context changed. Each block below replaces the one of its key you were shown before; one marked changed="lines" lists only the lines added (+) and removed (-). (withdrawn) ``` Mistakes to avoid: - Restarting, or `/new`, to pick up an edit. The next turn already carries it. A new session starts without the conversation. Instead: Send the next message. - Editing the file during a turn, for that turn. The file is read at the turn's first request. The edit lands at the next turn. Instead: Steer the running turn with the change, or wait for the next one.