Reference·Instruction filesIndexClose
Instruction files
Which files Nodecode reads into the prompt, where the model finds them, and when an edit takes effect.
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 <harness> block that starts From <path>:, operator-rules first. The system message holds only the session's folder and the manual's topics.
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 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.
~/mono/packages/api/src/routes. The search looks in three folders and reads packages/api/AGENTS.md. It never reaches ~/mono, where it would have stopped at .git.| 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. |
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. |
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 <system-reminder> 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.
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.