Workspace instructions

Workspace instructions are the standing notes you keep in files beside your work, so DataMind Oda follows the same rules every time it works in that folder, without you repeating them in every chat. They add to the rules your company sets for every chat; see Manage DataMind Oda for your company.

Which files Oda reads

Oda finds instruction files in two places, broadest first:

1. Your Oda home folder. An AGENTS.md in your Oda home folder applies wherever you work on this computer. Oda's home folder and settings files shows where that folder is.
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 on the way. The top is the nearest folder at or above the working folder that contains a .git entry (a .git folder, or the .git file of a Git worktree); when there is none, the walk starts at the working folder itself. The folder a chat works in is its workspace.

In each 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 instructions win. A file deeper in the tree takes precedence 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.
• Guidance, not an override. Oda treats the files as guidance: they do not override Oda's own instructions or what you ask for in the chat.
• Same folder only. A file must sit directly in the folder it applies to; a name that contains 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.

Add or edit 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.

To change the rules later, edit the file and let Oda work: the next load includes your change, and the chat records it.

When Oda picks up your files

• A new chat loads the instructions with its first message.
• Oda re-reads them after it reads, writes or edits files in the folder, so a file in a subfolder joins when work reaches that folder.
• A chat you come back to brings them up to date.

When a file joins, changes or is removed, Oda notes it in the chat's records:

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. System prompt, context and compaction shows where these records live and how to open them.

When the files do not all fit

Oda sends each batch of instruction files within a fixed budget of 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 never summarised: a file that is cut is cut, not rewritten.
• Oda notes in the chat's record which files were left out and which file was cut: Workspace instruction budget <maxBytes> bytes: omitted <paths>; truncated <path> from <N> to <M> bytes, with only the parts that apply.

To keep everything in play, keep the files short, and move detail that concerns one part of the project into that part's folder.

What Oda does not read

• Lowercase names such as agents.md, on a file system that tells upper and lower case apart. Where case is ignored, as on Windows and by default on macOS, agents.md is found as AGENTS.md.
• A .claude/rules/ folder.
• @path imports written inside an instruction file.

Write the notes in the file itself, and name it AGENTS.md or CLAUDE.md, or the matching local overlay.

Questions, answered

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 of it, or your Oda home folder for your work everywhere. The file must sit directly in that folder; a name that contains a path is not read.

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.

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.

Do folder files replace the company's Organization instructions?

No. The company's Organization instructions are added to every Oda chat, and the files in a folder add the rules for work there. Company-wide rules belong in the company settings, not in a folder file.

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.

When do my instructions start applying?

A new chat loads them with its first message. Oda checks them again after it reads, writes or edits files in the folder, and a chat you come back to brings them up to date.

Why has my change not applied yet?

Oda re-reads the 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 do the instruction notes in the chat mean?

They name a file whose instructions joined or changed.

• Updated instructions from: <path>: the file changed after it was loaded, and the new text is used from this load on.
• Instructions removed: <path>: the loaded file is gone. The note adds The previously loaded instructions from this file no longer apply.
• Additional instructions from: <path>: a file for a more specific folder joined. The note adds These instructions apply to work under <scope>.

What happens if the instruction files are too large?

Oda sends them within a 65,536-byte budget. When they 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; a file that is cut is cut, never rewritten. The record reads Workspace instruction budget <maxBytes> bytes: omitted <paths>; truncated <path> from <N> to <M> bytes. Keep the files short, or move detail that concerns one part of the project into that part's folder.

Are symbolic links to instruction files read?

Yes. An instruction file reached through a symbolic link is followed and read.

Does Oda read lowercase names, a rules folder or imports?

Oda looks only for AGENTS.md and CLAUDE.md. On a file system that ignores case, as on Windows and by default on macOS, agents.md is still found under that name; elsewhere it is not read. A .claude/rules/ folder is not read, and an @path import written inside an instruction file is not interpreted. Write the notes in the file itself.

Where can I see which instruction files Oda loaded?

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