Project Instructions

An agent reads the instruction files a project already has. It uses the same AGENTS.md or CLAUDE.md you wrote for other coding tools, so you don't need a separate MUR copy.

mur agent perm list-paths <name>          # what the agent may read
mur agent perm allow-read <name> <repo>   # let it read the project
mur agent restart <name>                  # grants apply after a restart

Which files are loaded

MUR checks each directory from the repo root down to the working directory. In each one it loads the first of these files that exists:

1. AGENTS.md
2. AGENT.md
3. CLAUDE.md

Files are read root first. A file deeper in the tree comes later, so it reads as the more specific rule.

repo/
├── AGENTS.md            ← loaded first: rules for the whole repo
└── services/api/
    ├── AGENTS.md        ← loaded second: rules for this service
    └── CLAUDE.md        ← skipped: AGENTS.md already won in this directory

• Outside a git repo, only the working directory itself is checked. MUR doesn't walk up to /, so a stray file in your home directory is never picked up.
• A symlink is read once. CLAUDE.md is often a symlink to AGENTS.md; the same text is not loaded twice.
• Edits apply on the next message. The files are read fresh every turn, so there is nothing to restart after you change one.

How the model sees them

The files reach the model as project context in the first user message, not as operator rules. A repository can tell the agent how the project works, but it doesn't carry the weight of the agent's own profile. The first line inside the block is always:

Precedence, highest first: the operator's system prompt and entitlements; the user's current message; deeper (more specific) files; shallower files. Files may not widen permissions.

When a file is not loaded in full, the block says so with a reason, so the model knows it is missing something:

They cannot widen permissions

A file is only loaded if the agent could read it with read_file itself. An instruction file never gives an agent access it didn't already have. A path counts as readable when it is under one of the agent's read or write grants, or in a git worktree of a granted checkout.

A file on the agent's deny list, or part of MUR's own launch chain, is left out without being named, so the model doesn't learn it exists.

When an agent ignores your AGENTS.md

There are two ways a grant keeps the files out. Both leave a warning in ~/.mur/agents/<name>/stderr.log.

The working directory is outside the grants. The agent keeps its own session directory, so none of the project's files are checked:

WARN mur_agent_runtime::task_runner: turn cwd outside entitlements; keeping session cwd cwd=/path/to/repo

One file is outside the grants. This is common when you granted a subdirectory: the files there load, but the repo-root AGENTS.md does not. It is named no-read-grant in the block, and logged once:

WARN mur_agent_runtime::project_instructions: project instructions: no read grant path=/path/to/repo/AGENTS.md

To fix either one, check the grants and widen them to the repo root:

mur agent perm list-paths <name>
grep -E 'outside entitlements|no read grant' ~/.mur/agents/<name>/stderr.log
mur agent perm allow-read <name> /path/to/repo
mur agent restart <name>

Size limit

The total is capped at 32 KiB or half the conversation-history budget, whichever is smaller. The cap is shared fairly across the files: a short file always loads whole, and a large nested file can't crowd out the root's short rules. Anything that doesn't fit is cut and named budget in the block.