Workspace instructions

Workspace instructions are the standing notes you keep in files named AGENTS.md, beside the work they describe. DataMind Oda reads them as guidance whenever it works in that folder, so the same rules reach every chat without being repeated. This page shows which files Oda reads, where they belong, and what Oda records when they change or stop applying.

Which files Oda reads

Oda finds instruction files in two places, in this order:

1. Your Oda home folder. An AGENTS.md there applies wherever you work on this computer. See Oda's home folder and settings files.
2. Your project, from the top down. Oda walks from the top of the project toward the folder the chat works in, reading the files it finds along the way. The top is the nearest folder at or above the working folder that contains a .git folder; when there is none, the walk starts at the working folder itself. A chat works in a workspace folder.

In each project folder, Oda reads a base file named AGENTS.md or CLAUDE.md, and a local overlay named AGENTS.local.md or CLAUDE.local.md beside it.

• More specific wins. A file deeper in the tree wins over one nearer the top, and the project files win over the home folder file. Oda notes when it sends them that more specific instructions take precedence over broader ones.
• Same folder only. A file must sit directly in the folder it applies to. A name written as a path is not read.
• Read once. When two files in the same folder hold the same text, Oda uses the text once.
• Links are followed. An instruction file reached through a symbolic link is read.

What Oda does not read:

• Lowercase names such as agents.md.
• A .claude/rules/ folder, or @path imports written inside an instruction file. Write the notes in the file itself.

Write or change an instruction file

1. Create a plain text file named AGENTS.md in the folder the instructions should cover: your workspace folder for the whole project, a subfolder for just that part of it, or your Oda home folder for your work everywhere.
2. Write the instructions in plain text or Markdown. Say what should always happen, what to avoid, and how finished work should look.

# Project notes
- Run the test suite before reporting a task done.
- Keep generated reports in the reports folder.

• When they load. A new chat loads the instructions with its first request. A running chat re-reads them after it reads, writes or edits files in the folder, and a resumed chat brings them up to date.
• When you change one. Edit the file and let Oda work: the next load includes your change, and Oda records it.

What Oda records when files change

When instruction files change or join the batch, Oda records a message naming the file:

The chat keeps these records: an instruction record shows which workspace files were loaded, added, updated or removed, and opening it shows the material itself. See System prompt, context and compaction.

When the files do not fit

Oda loads each batch of instruction files within a fixed budget: 65,536 bytes. When the files do not all fit, Oda leaves out whole broader files before it cuts the most specific one, so the instructions closest to the work survive. Instructions are bounded, never summarised: a file that is cut is cut, not rewritten.

The record reads Workspace instruction budget <maxBytes> bytes: omitted <paths>; truncated <path> from <N> to <M> bytes, with only the parts that apply. To avoid it, keep the files short, and move detail that concerns one part of the project into that part's folder.

Questions, answered

Which file name should I use, AGENTS.md or CLAUDE.md?

Either. Oda reads AGENTS.md and CLAUDE.md the same way, and an AGENTS.local.md or CLAUDE.local.md overlay beside them. When two files in one folder hold the same text, Oda uses the text once.

Where does an instruction file belong?

In the folder the instructions should cover: your workspace folder for the whole project, a subfolder for just that part, or your Oda home folder for your work everywhere. The file must sit directly in that folder; a name written as a path is not read.

Do instructions in a subfolder apply to the whole project?

No, they apply to work under that folder. Oda adds them when it works there and notes These instructions apply to work under <scope>. More specific instructions take precedence over broader ones, so a deeper file wins when both say something about the same thing.

When do my instructions start applying?

A new chat loads them with its first request. A running chat re-reads them after it reads, writes or edits files in the folder, and a resumed chat brings them up to date.

Why has my edit not shown up yet?

Oda re-reads instruction files as work goes on, not the moment you save. The change is picked up after Oda next reads, writes or edits files in that folder, or when the chat is resumed; right after a save, the older text can still be in use for a moment.

What happens if the instruction files are too large?

Oda loads them within a 65,536-byte budget: whole broader files are left out first, and the most specific file is cut last, so the instructions closest to the work survive. The record reads Workspace instruction budget <maxBytes> bytes: omitted <paths>; truncated <path> from <N> to <M> bytes, with only the parts that apply. Keep the files short, or move detail that concerns one part of the project into that part's folder.

Do my instructions override Oda's own rules?

No. Oda treats the files as guidance: more specific instructions take precedence over broader ones, but the files do not override Oda's own instructions or what you ask for in the chat.

Where can I see which instruction files were loaded?

In the chat's records. An instruction record shows which workspace files were loaded, added, updated or removed, and opening it shows the material itself; see System prompt, context and compaction.

Are symbolic links to instruction files read?

Yes. Oda follows a symbolic link to an instruction file and reads it.

Does Oda read lowercase file names or a rules folder?

No. Lowercase names such as agents.md are not read, and neither is a .claude/rules/ folder or an @path import written inside an instruction file. Name the file AGENTS.md or CLAUDE.md, and write the notes in the file itself.