> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mutagent.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Project context

> AGENTS.md / CLAUDE.md loads into the prompt in every mode, nearest file last, and reaches the agents Helix dispatches.

Helix reads your project's `AGENTS.md` or `CLAUDE.md` and places it **last** in the prompt — the
final thing the model reads before your turn, framed as your project's working rules. Put your
build commands, conventions and house rules there.

```bash theme={null}
echo "Build with: bun run build" >> CLAUDE.md
helix
```

## Which file wins

Discovery walks from the working directory **up through every ancestor**. In each directory the
first of these names wins and the rest are skipped — one file per directory, never merged:

`AGENTS.override.md` → `AGENTS.md` → `AGENTS.MD` → `CLAUDE.md` → `CLAUDE.MD`

The collected files render root-first with the **nearest file last**, so the closer a file is to
where you launched, the closer it sits to the model — and the more weight it carries when files
disagree.

With this tree, launched from `packages/api/`:

```
repo/
├── CLAUDE.md              ← loads first (repo-wide rules)
└── packages/
    └── api/
        └── AGENTS.md      ← loads last (nearest — wins where they disagree)
```

Both apply; `packages/api/AGENTS.md` has the final word. An `AGENTS.md` and a `CLAUDE.md` in the
*same* directory do not combine — `AGENTS.md` is earlier in the candidate order, so only it loads.

## Placement in the prompt

Your files close the assembled prompt — the last block before your turn, announced to the agent as
project instructions to follow. That placement is deliberate, and it is why the file actually gets
obeyed. Simplified to its skeleton (real block names, stand-in bodies), the prompt the model
receives looks like this:

```xml theme={null}
<agent>
  … how the harness works: tools, verification, output rules …
  <orchestrator type="runtime-protocol">
    … the Helix persona and routing protocol …
  </orchestrator>
  <runtime_state>
    … live facts: mounted skills, working directory, model …
  </runtime_state>
</agent>

<project_context>
  Project-specific instructions and guidelines:

  <project_instructions path="repo/CLAUDE.md">
    Build with: bun run build
  </project_instructions>
  <project_instructions path="repo/packages/api/AGENTS.md">
    API handlers stay framework-free; validation lives in schemas/.
  </project_instructions>
</project_context>

← your turn starts here
```

Each of your files arrives verbatim in its own `<project_instructions>` block, labelled with its
path, root first and nearest last.

It loads in every mode — the orchestrator, [agent mode](/helix/agent-mode), and Prime — and it
reaches the sub-agents Helix dispatches, which matters more than it sounds: an agent editing files
in your repository without your conventions will violate every one of them.

One exclusion, also deliberate: the binary ships internal files in its own bundle directory, and
those are **never** rendered as your project context — only files you wrote reach the block.