AGENTS.md Chain

The project context of a session is the AGENTS.md chain: every applicable file from the git root of the working directory down to the working directory itself, inclusive.

In plain words

• cwd (current working directory) — the folder the session “stands in”: where its commands start.
• git root — the top-level folder of a git repository (the folder that contains .git). It is the top of the versioned project.
• The chain — the ordered list of AGENTS.md files loaded along the path from the git root down to the cwd. git root → cwd reads as “from the top of the repository down to the current folder”. A folder’s AGENTS.md is the “operating manual” for an agent working in that folder: the further down the tree, the more specific the rules — so the agent reads them all, general first, specific last.

Situation	What the chain contains
Inside a git repository, deep in a subfolder	Every AGENTS.md from the repo root down to the cwd, inclusive
Inside a repository’s root folder	A single section: the root’s own AGENTS.md
Not a git repository (e.g. ~/workspace/vault.ducatillon.net)	Nothing to walk up to: the chain is [cwd] only — only a cwd/AGENTS.md would count; if none exists, the chain contributes zero bytes

The chain never scans sideways, never rises above the git root, and from a folder like ~/workspace/… never reaches ~/.hermes (not an ancestor of the cwd).

Two rules

Rule A — Scope (what is scanned): the chain covers git root → cwd inclusive. It never scans children below the cwd and never goes above the git root.

Rule B — Precedence (among what is scanned): the closer a directory is to the cwd, the later its section appears in the prompt — the local context follows the root context. This is a specificity convention, not a deterministic override mechanism: instructions should remain consistent, not rely on contradiction.

Do not confuse rule B with scanning children: children of the cwd remain excluded.

Mechanics

• The chain walks upward from the cwd until a .git directory is found. No .git found, or cwd = git root → the chain is [cwd] only.
• Each directory contributes its first existing file among AGENTS.override.md / AGENTS.md / agents.md (AGENTS.override.md wins in the same directory).
• Each contribution becomes a section labeled with its provenance; identical successive contents are deduplicated.
• Each section is truncated individually to the per-file budget, then the merged chain is capped again globally (see context file budget) — a deep monorepo cannot multiply the budget indefinitely.

Precedence of context families (only one family loads):

.hermes.md / HERMES.md  →  AGENTS.md chain  →  CLAUDE.md  →  .cursorrules

SOUL.md is independent of this chain and is read from the profile home. CONTEXT.md is never auto-discovered.

The host card (HERMES_HOME/AGENTS.md, e.g. ~/.hermes/AGENTS.md) is not a link of this chain. On hosted sessions (desktop, gateway) the gateway injects it directly from the profile home, independently of the cwd — verified 2026-09-13 on a desktop session whose cwd was ~/workspace/vault.ducatillon.net (outside ~/.hermes), which still received it. The chain itself can never reach that file from such a cwd; only the standalone mechanism delivers it. CLI one-shot sessions do not get it (chain strictly cwd-bound).

Example: YEU, cwd rates/

Git root /home/hermes/workspace/YEU (contains locationyeu.com/, rates/, _bmad/), session with cwd /home/hermes/workspace/YEU/rates/:

/home/hermes/workspace/YEU/AGENTS.md          ← git root section
/home/hermes/workspace/YEU/rates/AGENTS.md    ← cwd section (most specific, comes last)

There is no rates/src/ section in this example. Paths that are not ancestors of the cwd are not scanned:

Element (inside YEU)	Why absent from the chain
YEU/.agents/skills/ (79 project skills)	Child of the git root, not an ancestor of the cwd. Skills use the separate project-skills mechanism: <git-root>/.agents/skills + hermes skills trust
YEU/_bmad/, YEU/locationyeu.com/	Non-ancestor children of the cwd (or separate git roots)
~/.hermes/AGENTS.md (host)	Not part of this chain and not an ancestor of the cwd. It reaches hosted sessions (desktop/gateway) via the separate host-card injection — see Mechanics — regardless of cwd, never via this chain

Special cases

Case	Result
cwd = git root	Chain = [root] = [cwd], a single possible AGENTS.md section (the common case)
No git repository (e.g. ~/workspace/vault.ducatillon.net)	Chain = [cwd], only cwd/AGENTS.md counts; if none exists the chain contributes zero bytes
Gateway / desktop session	The chain follows the session cwd like any other session. On top of it, the gateway injects the host card (HERMES_HOME/AGENTS.md) directly — a desktop session with cwd ~/workspace/vault.ducatillon.net still receives it, independent of the cwd

Takeaways

• SOUL.md is the identity file, loaded directly, independent of the cwd.
• AGENTS.md follows the cwd: repo-scoped, increasing specificity toward the cwd.
• The host card is a separate gateway injection, not a chain link: hosted sessions (desktop/gateway) receive it regardless of cwd; CLI one-shot sessions do not.
• The git-root → cwd pattern exists in several harnesses (Copilot CLI, Claude Code, OpenCode) with different names, priorities, and limits — semantics are not transposed automatically.